Migrating to Connectum 1.0

This guide applies to applications upgrading from a release candidate or alpha to 1.0 or later. Make each applicable change and run your service's transport, authorization, and broker integration tests before deployment.

Upgrade Node.js

Published packages require Node.js >=22.13.0. Upgrade the runtime before installing 1.x packages. Packages ship compiled JavaScript; the higher Node.js floor for directly executing application TypeScript is a separate concern in Runtime Compatibility.

Enable Resilience Explicitly

createDefaultInterceptors() enables error handling and validation by default. Timeout, bulkhead, circuit breaker, retry, and fallback behavior is opt-in.

// Preserve the former implicit resilience set explicitly.
createDefaultInterceptors({
  timeout: true,
  bulkhead: true,
  circuitBreaker: true,
  retry: true,
});

Review whether each policy belongs on the inbound server path before preserving it. The circuit breaker now classifies infrastructure failures and is primarily an outbound/client pattern. See Built-in Interceptor Chain and the exact DefaultInterceptorOptions.

Use an HTTP/2-Capable Transport for Bidi Streaming

server.start() rejects a user service with a bidirectional-streaming method when the effective transport is plaintext HTTP/1.1. Configure h2c with allowHTTP1: false or use TLS with HTTP/2 negotiation.

Temporary compatibility modes are available through transportValidation: 'warn' | 'off', but they preserve a configuration in which bidi calls can hang or fail. Use the Transport Matrix to choose the production transport.

Remove PublishOptions.sync

Delete sync from EventBus publish options. It was a no-op: each adapter already waits for its broker-specific publish acknowledgement. No replacement is needed.

await eventBus.publish(OrderCreatedSchema, payload, {
  topic: 'orders.created',
});

Migrate Service Registration

If the application uses legacy ServiceRoute registration or manually builds cross-service clients, follow Migrating to the Service Catalog.

Verify the Upgrade

• Confirm all installed @connectum/* packages are on the intended release line.
• Run unary and streaming transport tests.
• Exercise validation, auth/authz, and explicitly enabled resilience behavior.
• Publish and consume a representative event through every configured adapter.
• Start and terminate the service to verify readiness and graceful shutdown.