Start9Labs/start-technologies start-sdk/v4.0.0

Start SDK v4.0.0

on GitHub

Highlights

• Configure HTTP proxy authentication and forwarded headers under bindPort's proxy option, independently of addSsl. Proxy authentication applies to both the original and TLS-wrapper legs.

• Inherit proxy defaults from the protocol: enabled for HTTP-family protocols, disabled otherwise. Every protocol accepts an explicit proxy object or proxy: null override.

• Move addSsl.auth to proxy.auth and addSsl.addXForwardedHeaders to proxy.addXForwardedHeaders when rebuilding packages. Keep TLS settings under addSsl.

• Require StartOS 0.4.1 or later for packages built with this SDK.

• Added sdk.host.getAddressGateways, which resolves the gateways publishing the addresses a service advertises beside the gateway its outbound connections leave through, for health checks that report a mismatch.

• Fixed daemon ready checks and addHealthCheck() checks using more memory every time they run while the service is up. Rebuild packages with this SDK version to receive the fix.

Security

• Keep daemon and subcontainer command environment values out of process command lines, splitting large environments into bounded chunks.
• Preserve multiline image environment values in packages built with start-cli 2.6.0 or later.
• Require StartOS 0.4.1 or later for packages built with this SDK.

Important

• Packages built with SDK 4.0.0 require StartOS 0.4.1 or later.

• For http/ws, use addSsl: null for plaintext HTTP proxying without a TLS wrapper. HTTP proxying for https/wss requires TLS termination; disable both proxy and addSsl for TLS passthrough.

• Before rebuilding, move addSsl.auth to proxy.auth and addSsl.addXForwardedHeaders to proxy.addXForwardedHeaders. For example:

  await host.bindPort(8080, {
    protocol: 'http',
    addSsl: { preferredExternalPort: 443 },
    proxy: {
      auth: { type: 'bearer', tokens: [apiToken], realm: null },
      addXForwardedHeaders: true,
    },
  })

• Raw TCP (protocol: null), SSH, and DNS default to proxy: null. For services without HTTP handling, remove obsolete addXForwardedHeaders: false and auth: null SSL fields rather than moving them into proxy. An explicit HTTP proxy requires HTTP traffic regardless of the chosen protocol's defaults.

• Proxy authentication covers all enabled HTTP addresses, including plaintext and bridge connections. Clients using those addresses must supply credentials too.

• With forwarded headers enabled, TLS legs generate X-Forwarded-Proto: https. Plaintext legs strip client-supplied X-Forwarded-Proto and generate no replacement.

• Already-compiled packages remain supported by StartOS's legacy binding decoder; source migration is required when rebuilding with SDK 4.0.0.

• Replace health-check returns of result: 'waiting' with result: 'starting', waiting: true. Use result: 'loading', waiting: true for an operational service waiting on an external condition. Remove waiting interval entries from statusTrigger configurations; those checks now use the interval for their starting or loading result. The default triggers still back off waiting checks.

• Nonempty health-check messages are displayed verbatim for every status. Include the complete message rather than relying on the UI to add a “Waiting on” prefix or ellipsis. Empty or absent messages use the localized status label.

• Failure probes softened to starting during the grace period omit their error message. Packages built with older SDKs still forward that message; the UI displays it as supplied, since it cannot distinguish those results from custom starting messages.