VgiRpcServer

Defined in: src/server.ts:134

RPC server that reads Arrow IPC requests from stdin and writes responses to stdout. Supports unary and streaming (producer/exchange) methods.

It is also the protocol host every other transport serves: hand the same instance to serveTcp, serveUnix, serveStream or createHttpHandler and each serves exactly the protocols registered here, routed, gated and error-encoded by the same code.

Constructors

Constructor

new VgiRpcServer(protocol, options?): VgiRpcServer;

Defined in: src/server.ts:162

Parameters

Parameter	Type
protocol	Protocol
options?	VgiRpcServerOptions

Returns

VgiRpcServer

Accessors

id

Get Signature

get id(): string;

Defined in: src/server.ts:211

This server’s identifier, as written on every response batch.

Returns

string

---

identity

Get Signature

get identity(): IdentityImpl | undefined;

Defined in: src/server.ts:206

The hosted vgi_rpc.Identity.v1 implementation, when there is one. Its sealed grants and resolveToken are what an HTTP handler accepts as bearer credentials.

Returns

IdentityImpl | undefined

---

includeTracebacks

Get Signature

get includeTracebacks(): boolean;

Defined in: src/server.ts:232

Whether this server’s error batches carry the remote traceback. One switch for every transport, on by default (WIRE_PROTOCOL.md §8).

Returns

boolean

Methods

addProtocol()

addProtocol(target, label?): void;

Defined in: src/server.ts:315

Host an additional application protocol alongside the primary.

Prefer the protocols constructor option, which fixes the set at construction. Refused once the server has started serving, for a reserved vgi_rpc. name (checked on the binding name and the protocol’s own name, however either was derived), and for a duplicate name.

Parameters

Parameter	Type	Default value
target	Protocol | ProtocolBinding	undefined
label	string	"addProtocol"

Returns

void

---

bindings()

bindings(): Map<string, ProtocolBinding>;

Defined in: src/server.ts:219

Every protocol this server hosts, primary first.

The primary is projected from the server’s own protocol rather than stored, so the existing registration paths keep working untouched.

Returns

Map<string, ProtocolBinding>

---

notifyTransport()

notifyTransport(kind): Promise<void>;

Defined in: src/server.ts:396

Fire the on_serve_start hook once for this server. Idempotent on success; re-throws on failure without committing, so the next request retries. Concurrent first requests share one attempt. Also seals the hosted set.

Parameters

Parameter	Type
kind	TransportKind

Returns

Promise<void>

---

registerIdentity()

registerIdentity(identity): void;

Defined in: src/server.ts:300

Host vgi_rpc.Identity.v1 on this server, when the deployment configured it. Prefer the identity constructor option, which registers it in the canonical place (after reflection).

Only the methods whose hooks the deployment supplied are hosted, so the binding’s protocol_hash narrows with them: a method this worker cannot answer is better absent than routed-and-refusing, because then what the server hosts describes what it actually does and a client learns it from reflection rather than by calling and reading an error. With neither hook configured nothing is registered at all – which is what keeps a dependency upgrade from growing a credential-to-identity oracle on every existing worker.

Not version-exempt: the binding declares no protocolVersion, so the gate never fires, and exempting it would be a claim rather than a fact.

Reachable on every transport this server is handed to. Its guards read the caller’s AuthContext: HTTP and TCP-with-peer-identity supply one; stdio and unix do not, so there it fails closed.

Parameters

Parameter	Type
identity	IdentityImpl

Returns

void

---

registerReflection()

registerReflection(): void;

Defined in: src/server.ts:266

Host vgi_rpc.Reflection.v1 on this server.

Registered after the application protocols so it appears in its own output without being special-cased, and so the primary stays the application protocol – which is what the single-protocol accessors report.

The binding is version-exempt: this is the protocol a version-mismatched client calls to learn what mismatched, and gating it would deny the client the diagnosis it came for.

Idempotent, because the constructor already calls it unless the deployment opted out: an explicit second call should not turn a working server into a duplicate-name error.

Returns

void

---

resolve()

resolve(protocol, method): object;

Defined in: src/server.ts:353

Resolve one request’s (protocol, method) pair.

The routing key is required, including against a server hosting exactly one protocol: an exemption would let an intermediary that rebuilds a request and drops the field land silently on whichever protocol happened to be first, rather than being told.

The three failures are deliberately distinct, and a client depends on the difference – particularly the last, which is the documented capability-probe signal: a client testing for an optional method must be able to tell “you do not speak this protocol” from “you speak it but lack this method”.

Parameters

Parameter	Type
protocol	string
method	string

Returns

binding

binding: ProtocolBinding;

The binding that owns it – the source of the access record’s identity.

method

method: MethodDefinition;

The resolved method definition.

---

run()

run(): Promise<void>;

Defined in: src/server.ts:419

Start the server loop over stdin/stdout. Reads requests until stdin closes.

Returns

Promise<void>

---

seal()

seal(): void;

Defined in: src/server.ts:239

Fix the hosted set. Called by every transport when it starts serving; idempotent. After this addProtocol, registerReflection and registerIdentity throw.

Returns

void

---

serveConnection()

serveConnection(
   readable,
   writable?,
   transportKind?,
   peer?
): Promise<void>;

Defined in: src/server.ts:451

Serve requests over an explicit byte-stream pair until the readable ends — the transport-agnostic core that run (stdin/stdout) is built on.

Use this to serve over any duplex channel that the stdio/unix/tcp helpers don’t cover: a Web Worker / MessagePort bridge, an in-memory pipe, or a pre-connected socket. The loop, on_serve_start firing, and EOF/broken-pipe handling are identical to run.

Parameters

Parameter	Type	Default value	Description
readable	ReadableStream<Uint8Array<ArrayBufferLike>> | ReadableStream	undefined	incoming request bytes — a web ReadableStream<Uint8Array> or a Node Readable (e.g. a Duplex bridging a MessagePort).
writable?	number | Socket | ByteSink	undefined	outgoing response sink — a stdout-like fd number, or a net.Socket / structurally-compatible Duplex. Omit for the stdout fd.
transportKind?	TransportKind	TransportKind.PIPE	reported to the on_serve_start hook, and deciding the traceback default (default PIPE).
peer?	RawPeer	{}	the caller, when the transport resolved one.

Returns

Promise<void>