nexus
Core guides

Connections

Acquire a shared session by exact target or wait for an incoming peer.

Before getting a service, acquire a Connection. It represents one ready, bidirectional session between two configured Nexus runtimes.

Examples below assume app is your configured runtime and target comes from your adapter’s exact target constructor. See Adapters for the platform setup.

Connect To A Known Target

const connection = await app.connect({ target });
const documents = connection.get(DocumentToken);

Nexus reuses a ready session matching that address or starts a connection attempt. The application chooses the address, including any active-tab, frame, or process discovery needed to obtain it. A failed attempt is reported without automatic retry.

The remote side can get your services over the same session; physical connection direction does not impose client/server RPC roles.

Constrain The Peer

Add where to check the peer identity and locally observed connection facts:

const connection = await app.connect({
  target,
  where: (contextMeta, connectionMeta) =>
    matchesWorkspace(contextMeta) && acceptsTransport(connectionMeta),
});

matchesWorkspace and acceptsTransport are application predicates over your adapter model. Both the target and the predicate must match. A mismatch does not make Nexus search elsewhere or redial.

The predicate selects a connection at acquisition time. Later calls use that session without re-running it. Use policy for connection admission and per-call authorization.

Wait For A Peer To Connect

Omit target when another context will establish the connection:

const connection = await app.connect({
  where: matchesWorkspace,
  timeout: 10_000,
});

This waits for exactly one matching ready session. It never dials or searches for a service. More than one match is an ambiguity error. To take all current matches, use multiple connections.

Connect During Startup

An endpoint’s connectTo lists exact targets to dial once after listening starts:

app.configure({
  endpoint: { ...endpointConfig, connectTo: [target] },
});

endpointConfig is your adapter’s endpoint configuration. Standard adapter helpers can also accept connectTo. Startup dialing needs no Token, does not wait for providers, and is not awaited by ready(). Failures are logged. There is no automatic reconnect. Omitting the list starts no outgoing connections; [] clears an inherited list during configuration composition.

For a parent creating a child context, the parent starts listening first. The child can then dial the parent once, while the parent waits passively for it.

Waiting And Ownership

Concurrent acquisitions can share one connection attempt. A timeout or an aborted signal ends this caller’s wait without closing a shared session. See Errors and timeouts for budgets and cancellation.

The runtime owns the connection. Dropping your local handle does not disconnect it. connection.disconnect() ends it for every user of that session. See Connection lifecycle.

Edit this page on GitHub