Typert 远程调用
English | 中文
以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。Typert Gateway Agent Note 负责架构与传输决策；本页记录 dsh-typert-protocol 和 dsh-api-gateway 中公共约定的字面定义。
Lookup 与上下文声明
业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；上下文声明将一种作用域上下文类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
```ts type-equiv /* Merge-extensible Host object lookup declarations. / interface TypertLookupMap {}
```ts type-equiv
/** Merge-extensible scoped Context declarations. */
interface TypertContextMap {}
lookup 的 resolver 卸载后，注册表仍会保留其 wire 声明。因此 SRC 发现过程会继续把该参数归类为 lookup，并因不可用而失败，而不会把 wire 值当作普通业务对象接受。
```ts type-equiv / Stable wire declaration retained after a lookup provider unloads. */ interface TypertLookupDefinition { / Merge-declared lookup key. / readonly key: string / Source parameter name recognized by the SRC weak parser. / readonly parameter: string / Wire field replacing the Host object parameter. */ readonly wire: string / Canonical Host type symbol used by strict generation. / readonly hostTypeSymbol: string / Canonical wire type symbol used by strict generation. / readonly wireTypeSymbol: string }
## 调用 descriptor
`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema factory，SRC codec 则在不恢复结构类型的前提下强制要求输入为 JSON 安全值。一元结果 codec 可提供 `encode()` 处理含字节的子树，并通过 `decode()` 递归校验原生字节；Client 声明将每个 `Uint8Array` 限定为以 `ArrayBuffer` 为底层缓冲区。纯 JSON 结果无需字节识别或 Client 解码。取消通过带外 carrier signal 表达：它在业务参数之后注入，绝不进入 `args`。
```ts type-equiv
/** Codec attached to one invocation parameter or result. */
type TypertCodec =
| {
readonly mode: 'strict'
readonly typeSymbol: string
/** Materialize and return the process-realm schema on first boundary use. */
readonly create: () => TypertSchema
/**
* Decode a unary result whose fields require type-specific handling.
* @param value - result reconstructed by the RPC carrier.
* @returns the validated result, retaining native byte views.
*/
readonly decode?: (value: unknown) => unknown
/**
* Project typed binary fields into RPC result attachments.
* @param value - native unary result.
* @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
* @returns JSON metadata with untouched JSON subtrees retained.
*/
readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown
}
| {
readonly mode: 'src-json'
}
``ts type-equiv
/** One ordered business parameter in a Remote invocation. */
interface InvocationParameterDescriptor {
/** Source-level parameter name. */
readonly name: string
/** Required key in the wireargsobject. */
readonly wire: string
/** Whether the value is JSON or requires a registered Host lookup. */
readonly source: 'json' | 'lookup'
/** Lookup key whensourceislookup. */
readonly lookup?: string
/** Boundary codec for the wire representation. */
readonly codec: TypertCodec
/** Missing wire fields decode toundefinedonly for an explicitly declaredT | undefined`. */
readonly acceptsUndefined?: true
}
```ts type-equiv
/** Carrier-independent description of one exported method invocation. */
interface InvocationDescriptor {
/** Globally stable generated identity. */
readonly id: string
/** Cordis service key owning the method. */
readonly service: string
/** Wire namespace, defaulting to the service key. */
readonly namespace: string
/** Public instance method name. */
readonly method: string
/** Service member invoked when the exported method name is an alias. */
readonly implementation?: string
/** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
readonly mode?: 'stream'
/** Receiver selection mode. */
readonly invocation:
| { readonly kind: 'direct' }
| {
readonly kind: 'context'
readonly context: string
readonly wire: string
readonly codec: TypertCodec
}
/** Optional consuming-Context projection for one direct lookup parameter. */
readonly scope?: {
/** Context kind whose Client adapter supplies the identity. */
readonly context: string
/** Lookup parameter wire field replaced by the Context identity. */
readonly wire: string
}
/** Ordered business parameters. */
readonly parameters: readonly InvocationParameterDescriptor[]
/**
* Client-to-Host items of the same logical stream, generated from the `In`
* type argument of the method's `RemoteStream<Out, In>` return type; absent
* when `In` is `never`. The method reads the items through
* `RemoteInvocation.uplink()`, so nothing enters the parameter list.
*/
readonly uplink?: {
/** Codec validating every uplink item before `uplink()` delivers it. */
readonly codec: TypertCodec
}
/** Transport cancellation injected after business parameters instead of entering wire args. */
readonly cancellation?: {
/** Reserved final Host method parameter. */
readonly parameter: 'signal'
}
/** Codec for the unary result or each yielded stream item. */
readonly result: TypertCodec
/** Source declaration used only for diagnostics. */
readonly sourceLocation?: InvocationSourceLocation
}
Host 别名 RemoteStream<Out, In> 同时命名一条流的两个方向，接收方法通过 this.ctx.invocation 读取本次调用的上下文：
``ts type-equiv
/**
* One Remote stream as a Host method returns it: the items it yields to the
* Client, iterated as a plainAsyncIterable.Inis the type of the
* items the Client may send back on the same logical stream, read through
*RemoteInvocation.uplink(); it is carried only as a type-level marker. The
* defaultneverdeclares a method that reads none, and its descriptor
* carries no uplink codec. A generated Client stream method returns the same
* stream as aRemoteStreamHandle.
* @template Out - item type the Host method yields.
* @template In - item type the Client may send;never` when the method reads none.
*/
type RemoteStream
```ts type-equiv
/**
* One open Remote stream as the Client holds it: the downlink items as an
* `AsyncIterable`, plus the uplink and cancellation of the same logical
* stream. A generated Client stream method returns it, and calling that
* method opens the stream: a holder that neither iterates nor disposes the
* handle keeps the Host stream alive. A handle stands for one generation:
* when the carrier is lost, iteration fails with the carrier error and the
* handle is finished.
* @template Out - item type the Host method yields.
* @template In - item type the Client may send; `never` when the method reads none.
*/
interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
/**
* Send one uplink item. Items sent before the stream has opened are queued
* and sent once the `open` frame is on the wire. A top-level `undefined`
* travels as an `item` frame without `value`.
* @param item - item the Host validates against the method's uplink codec.
* @throws {Error} when the item is not a lossless JSON value, when `end()`
* was called, or once the stream has terminated.
*/
send(item: In): void
/** Half-close the uplink: the Host's `uplink()` iteration ends. Idempotent; ignored after termination. */
end(): void
/**
* Cancel the logical stream: send `cancel` unless a terminal frame has
* arrived, and end the downlink iterator quietly. Breaking out of
* `for await` early does the same.
*/
dispose(): void
}
``ts type-equiv
/**
* One Peer's session on this Host. Connection owns it:ctxis the Cordis
* scope that owns connection-lifetime registrations and is disposed with the
* Peer. Who the Peer is and what it may do are not recorded here.
*/
interface PeerScope {
readonly id: PeerId
readonly ctx: Context
/**
* Tear down every registration made throughctx`.
* @returns settles once the scope has quiesced; racing calls share one completion.
*/
dispose(): Promise
```ts type-equiv
/**
* The context of one Remote call, reachable inside the receiving method as
* `this.ctx.invocation`. The Gateway derives the receiver from a Context that
* carries it, so no parameter is injected and nothing crosses the wire.
*/
interface RemoteInvocation {
readonly request: {
readonly namespace: string
readonly method: string
readonly args: Readonly<Record<string, unknown>>
}
/** Cordis service key of the receiving Service. */
readonly service: string
/** Peer the call speaks for; an in-process carrier speaks for the operator. */
readonly peer: PeerScope
/** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
readonly signal: AbortSignal
/**
* The Client's uplink items for this call. Available once; a second call
* throws. With an uplink codec on the descriptor every item is decoded to
* `In`; without one items arrive as `unknown` after a JSON-safety check.
* Iteration ends when the Client ends its uplink; when the method finishes
* its downlink the Gateway calls the iterator's `return()` and unread items
* are dropped. `In` is the caller's assertion: the runtime decodes by the
* descriptor and does not cross-check it.
* @template In - item type the caller reads; the descriptor codec decides what arrives.
* @returns the single-consumer uplink iterable.
*/
uplink<In = unknown>(): AsyncIterable<In>
}
Typert 注册表
ctx.typert 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与作用域上下文提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
```ts type-equiv /* Minimal Typert runtime consumed through dependency inversion. / interface TypertRegistryContract { readonly local: TypertLocalRegistry readonly remotes: TypertRemoteRegistry readonly lookups: TypertLookupRegistry readonly contexts: TypertContextRegistry }
生成的消费方声明会把 direct namespace 合并到 `TypertClientRemote` 继承的 map 中。
```ts type-equiv
/** Merge-extensible direct namespace surface generated for Client Remote services. */
interface TypertRemoteNamespaceMap {}
Host Gateway
Connection 会先解码 carrier envelope，再调用 ctx.typertGateway。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败由 TypertGatewayError 承载，其 gateway/* 码就是普通的 RemoteError 码，因此 RPC 适配器会把每个经结构识别的 RemoteError 连同其 code 与 details 原样放行，只把无法识别的异常归并为 gateway/internal。
``ts type-equiv
/** One Remote method request after a carrier has decoded its envelope. */
interface InvokeRemoteRequest {
/** Remote namespace selected by the generated descriptor. */
readonly namespace: string
/** Exported Service method name. */
readonly method: string
/** Named wire values; fields must exactly match the descriptor. */
readonly args: Readonly<Record<string, unknown>>
/**
* Client uplink items of this logical stream, delivered to the method through
*invocation.uplink()`; absent means an immediately ended iterable.
/
readonly uplink?: AsyncIterable
```ts type-equiv
/** Stable infrastructure and boundary failures emitted before or after business execution. */
type TypertGatewayErrorCode =
| 'gateway/ambiguous-endpoint'
| 'gateway/arguments-invalid'
| 'gateway/binding-invalid'
| 'gateway/context-failed'
| 'gateway/context-not-found'
| 'gateway/context-unavailable'
| 'gateway/definition-unavailable'
| 'gateway/input-invalid'
| 'gateway/invocation-unavailable'
| 'gateway/lookup-failed'
| 'gateway/lookup-not-found'
| 'gateway/lookup-unavailable'
| 'gateway/method-unavailable'
| 'gateway/protocol'
| 'gateway/provider-mismatch'
| 'gateway/result-invalid'
| 'gateway/service-unavailable'
| 'gateway/signature-invalid'
| 'gateway/uplink-overflow'
```ts type-equiv
/ Host dispatcher consumed by Connection adapters. */
interface TypertGateway {
/ Carrier adapter shared by WebSocket and in-process transports. /
readonly wireStream: TypertGatewayWireStream
/
* Check for an active Client event stream.
* @returns whether a stream is open and has not been cancelled.
/
hasLiveClient(): boolean
/
* Register the application-selected forwarded-event source.
* @param source - stream factory installed by the Remote assembly.
* @param host - stable Host facts included in each Client generation's opening frame.
* @returns disposer removing this exact source and cancelling its active streams.
*/
registerRemoteEvents(
source: TypertRemoteEventSource,
host: RemoteEventHostInfo,
): () => Promise
## 消费方 Remote
`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子服务，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务服务类型都不会进入消费方。
```ts type-equiv
/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
interface TypertClientRemote extends TypertRemoteNamespaceMap {
/**
* Mount one generated Host-for-Client contribution in the caller's fiber.
* @param contribution - explicitly selected Remote package artifact.
* @returns disposer after namespace services and concrete methods are ready.
*/
$mount(contribution: TypertRemoteContribution): Promise<TypertDisposer>
/**
* Subscribe to one forwarded Host event. Notifications run in registration
* order and isolate failures; scoped waterfalls return, delegate through
* `next()`, or reject the Host dispatch.
* @template Event - forwarded event name selected by the Host assembly.
* @param event - forwarded Host event name, unchanged on the wire.
* @param listener - receives the Client projection of the Cordis `Events` declaration.
* @returns disposer owned by the calling fiber.
*/
$on<Event extends TypertRemoteEvent>(event: Event, listener: TypertClientEventListener<Event>): () => void
}
Cordis API
Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.typert — TypertRegistry
Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
```ts cordis-catalog /* * Register one generated contribution atomically for the calling fiber. * Duplicate package-face identities, schemas, invocation ids, or endpoints * reject the whole batch. * @param contribution - generated schemas, reflection, and Host invocations. * @returns the exact effect disposer that removes this contribution. / register(contribution: TypertContribution): TypertDisposer
/*
* Look up one schema by <package>#<name>.
* @param key - global schema key.
* @returns a record containing the cached schema, or undefined when absent.
/
get(key: string): TypertSchemaRecord | undefined
/* * Resolve one required schema. * @param key - global schema key. * @returns a record containing the cached schema. * @throws when the key is malformed, the package face is absent, or the schema is not contributed. / resolve(key: string): TypertSchemaRecord
/* * Enumerate live schemas in registration order. * @param filter - optional package and face restriction. * @returns matching records containing the cached schemas. / list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
/*
* Look up generated reflection for one package face.
* @param packageName - exact npm package name.
* @param face - face to query; defaults to the host runtime.
* @returns the live package record, or undefined when absent.
/
getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
/* * Enumerate generated package reflection in registration order. * @param filter - optional package and face restriction. * @returns matching package records. / listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
/* * Project a live Zod schema to JSON Schema without caching the result. * @param key - global schema key. * @param params - Zod projection parameters. * @returns a fresh JSON Schema document. / toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
Types: [TypertContribution](invariants.zh.md) · [TypertFace](invariants.zh.md) · [TypertPackageFilter](invariants.zh.md) · [TypertPackageRecord](invariants.zh.md) · [TypertSchemaFilter](invariants.zh.md) · [TypertSchemaRecord](invariants.zh.md)
Source: [`packages/typert/registry/src/service.ts`](../../packages/typert/registry/src/service.ts)
<a id="ctxtypertgateway--typertgatewayservice"></a>
### `ctx.typertGateway` — `TypertGatewayService`
Resolve strict generated definitions or conservative SRC markers against current Cordis Services and Typert providers.
```ts cordis-catalog
/**
* Check for an active Client event stream.
* @returns whether a stream is open and has not been cancelled.
*/
hasLiveClient(): boolean
/**
* Register the sole application-selected forwarded-event source.
* @param source - stream factory installed by the Remote assembly.
* @param host - stable Host facts included in each Client generation's opening frame.
* @returns disposer removing this source and cancelling its active streams.
*/
registerRemoteEvents( source: TypertRemoteEventSource, host: RemoteEventHostInfo, ): () => Promise<void>
/**
* Invoke one live Remote method through strict generated reflection or SRC markers.
* @param request - decoded endpoint and exact named wire arguments.
* @returns the business result without output decoding.
* @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
*/
async invoke(request: InvokeRemoteRequest): Promise<unknown>
/**
* Open one live stream Remote method without assuming a physical carrier.
* @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
* @returns a cancellation-aware iterable over the business results.
*/
async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>