capnweb 0.0.0-409821 → 0.0.0-43aa384

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -39,7 +39,8 @@ interface StubBase<T = unknown> extends Disposable {
39
39
  }
40
40
  type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
41
41
  type TypedArray = Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | BigUint64Array | BigInt64Array | Float32Array | Float64Array; // This represents all the types that can be sent as-is over an RPC boundary
42
- type BaseType = void | undefined | null | boolean | number | bigint | string | TypedArray | ArrayBuffer | DataView | Date | Error | RegExp | Blob | ReadableStream<Uint8Array> | WritableStream<any> // Chunk type can be any RPC-compatible type
42
+ type BaseType = void | undefined | null | boolean | number | bigint | string | TypedArray | ArrayBuffer | DataView | Date | Error | RegExp | Blob | ReadableStream<any> // Chunk type can be any RPC-compatible type
43
+ | WritableStream<any> // Chunk type can be any RPC-compatible type
43
44
  | Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
44
45
  // prettier-ignore
45
46
  type Stubify<T> = T extends Stubable ? Stub<T> : T extends Promise<infer U> ? Stubify<U> : T extends StubBase<any> ? T : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>> : T extends Set<infer V> ? Set<Stubify<V>> : T extends [] ? [] : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>] : T extends readonly [] ? readonly [] : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>] : T extends Array<infer V> ? Array<Stubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>> : T extends BaseType ? T // When using "unknown" instead of "any", interfaces are not stubified.
@@ -107,6 +108,32 @@ type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown>
107
108
  });
108
109
  //#endregion
109
110
  //#region src/serialize.d.ts
111
+ /**
112
+ * Encoding levels determine what representation the RPC system hands to the transport.
113
+ * Each level names what the transport can assume about message values.
114
+ *
115
+ * - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
116
+ * - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
117
+ * - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
118
+ * - `"structuredClonable"`: Structured-clonable native values pass through where possible.
119
+ *
120
+ * @example
121
+ * ```ts
122
+ * // What happens to Uint8Array([1, 2, 3]) at each level:
123
+ * "string" → '["bytes","AQID"]' // JSON string with base64
124
+ * "jsonCompatible" → ["bytes", "AQID"] // JS array with base64
125
+ * "jsonCompatibleWithBytes" → ["bytes", Uint8Array] // JS array with raw bytes
126
+ * "structuredClonable" → ["bytes", Uint8Array] // + Date, BigInt stay native
127
+ * ```
128
+ */
129
+ type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
130
+ interface RpcLimits {
131
+ maxBigIntDigits: number;
132
+ maxDepth: number;
133
+ maxMessageSize: number;
134
+ }
135
+ declare const DEFAULT_MAX_DEPTH = 256;
136
+ declare const DEFAULT_LIMITS: RpcLimits;
110
137
  /**
111
138
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
112
139
  * RPC stubs, but it will support basic data types.
@@ -119,14 +146,21 @@ declare function deserialize(value: string): unknown;
119
146
  //#endregion
120
147
  //#region src/rpc.d.ts
121
148
  /**
122
- * Interface for an RPC transport, which is a simple bidirectional message stream. Implement this
123
- * interface if the built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
149
+ * Interface for a string-based RPC transport. This is the default transport type — no
150
+ * `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
151
+ * built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
124
152
  */
125
153
  interface RpcTransport {
126
154
  /**
127
- * Sends a message to the other end.
155
+ * The encoding level this transport works with. For this interface it is always "string";
156
+ * it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
128
157
  */
129
- send(message: string): Promise<void>;
158
+ readonly encodingLevel?: "string";
159
+ /**
160
+ * Sends a message to the other end. May optionally return a promise; if the promise rejects,
161
+ * the session is aborted.
162
+ */
163
+ send(message: string): void | Promise<void>;
130
164
  /**
131
165
  * Receives a message sent by the other end.
132
166
  *
@@ -145,6 +179,45 @@ interface RpcTransport {
145
179
  */
146
180
  abort?(reason: any): void;
147
181
  }
182
+ /**
183
+ * Interface for a transport that receives partially encoded JS values instead of JSON strings.
184
+ * The selected `encodingLevel` describes what the transport can assume about message values.
185
+ */
186
+ interface RpcTransportWithCustomEncoding {
187
+ /**
188
+ * The encoding level this transport works with.
189
+ *
190
+ * - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
191
+ * - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
192
+ * - "structuredClonable": Structured-clonable native values pass through where possible.
193
+ */
194
+ readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
195
+ /**
196
+ * Encodes and sends a message to the other end. Returns the encoded byte size if known.
197
+ * If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
198
+ * flow control. Send errors should be propagated via `receive()` rejecting.
199
+ */
200
+ send(message: unknown): number | void;
201
+ /**
202
+ * Receives and decodes a message sent by the other end.
203
+ *
204
+ * If and when the transport becomes disconnected, this will reject. The thrown error will be
205
+ * propagated to all outstanding calls and future calls on any stubs associated with the session.
206
+ * If there are no outstanding calls (and none are made in the future), then the error does not
207
+ * propagate anywhere -- this is considered a "clean" shutdown.
208
+ */
209
+ receive(): Promise<unknown>;
210
+ /**
211
+ * Indicates that the RPC system has suffered an error that prevents the session from continuing.
212
+ * The transport should ideally try to send any queued messages if it can, and then close the
213
+ * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
214
+ * before abort() is called is often an "abort" message, which communicates the error to the
215
+ * peer, so if that is dropped, the peer may have less information about what happened.)
216
+ */
217
+ abort?(reason: any): void;
218
+ }
219
+ /** Any supported transport type. */
220
+ type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
148
221
  /**
149
222
  * Options to customize behavior of an RPC session. All functions which start a session should
150
223
  * optionally accept this.
@@ -162,6 +235,16 @@ type RpcSessionOptions = {
162
235
  * to serialize the error with the stack omitted.
163
236
  */
164
237
  onSendError?: (error: Error) => Error | void;
238
+ /**
239
+ * Overrides for the resource limits enforced while deserializing messages from the peer. Any
240
+ * field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
241
+ * attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
242
+ *
243
+ * Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
244
+ * the peer never learns these values. A message that exceeds a limit is rejected, aborting the
245
+ * session.
246
+ */
247
+ limits?: Partial<RpcLimits>;
165
248
  };
166
249
  //#endregion
167
250
  //#region src/websocket.d.ts
@@ -170,6 +253,17 @@ type RpcSessionOptions = {
170
253
  * with the given `localMain`.
171
254
  */
172
255
  declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
256
+ /**
257
+ * Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
258
+ * `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
259
+ */
260
+ declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
261
+ #private;
262
+ constructor(webSocket: WebSocket);
263
+ send(message: T): void;
264
+ receive(): Promise<T>;
265
+ abort(reason: any): void;
266
+ }
173
267
  //#endregion
174
268
  //#region src/batch.d.ts
175
269
  /**
@@ -244,7 +338,7 @@ interface RpcSession<T extends RpcCompatible<T> = undefined> {
244
338
  drain(): Promise<void>;
245
339
  }
246
340
  declare const RpcSession: {
247
- new <T extends RpcCompatible<T> = undefined>(transport: RpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
341
+ new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
248
342
  };
249
343
  /**
250
344
  * Classes which are intended to be passed by reference and called over RPC must extend
@@ -297,7 +391,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
297
391
  * credentials as parameters and returns the authorized API), then cross-origin requests should
298
392
  * be safe.
299
393
  */
300
- declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
394
+ declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
301
395
  //#endregion
302
- export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
396
+ export { type AnyRpcTransport, DEFAULT_LIMITS, DEFAULT_MAX_DEPTH, type EncodingLevel, type RpcCompatible, type RpcLimits, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
303
397
  //# sourceMappingURL=index-workers.d.cts.map
@@ -39,7 +39,8 @@ interface StubBase<T = unknown> extends Disposable {
39
39
  }
40
40
  type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
41
41
  type TypedArray = Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | BigUint64Array | BigInt64Array | Float32Array | Float64Array; // This represents all the types that can be sent as-is over an RPC boundary
42
- type BaseType = void | undefined | null | boolean | number | bigint | string | TypedArray | ArrayBuffer | DataView | Date | Error | RegExp | Blob | ReadableStream<Uint8Array> | WritableStream<any> // Chunk type can be any RPC-compatible type
42
+ type BaseType = void | undefined | null | boolean | number | bigint | string | TypedArray | ArrayBuffer | DataView | Date | Error | RegExp | Blob | ReadableStream<any> // Chunk type can be any RPC-compatible type
43
+ | WritableStream<any> // Chunk type can be any RPC-compatible type
43
44
  | Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
44
45
  // prettier-ignore
45
46
  type Stubify<T> = T extends Stubable ? Stub<T> : T extends Promise<infer U> ? Stubify<U> : T extends StubBase<any> ? T : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>> : T extends Set<infer V> ? Set<Stubify<V>> : T extends [] ? [] : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>] : T extends readonly [] ? readonly [] : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>] : T extends Array<infer V> ? Array<Stubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>> : T extends BaseType ? T // When using "unknown" instead of "any", interfaces are not stubified.
@@ -107,6 +108,32 @@ type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown>
107
108
  });
108
109
  //#endregion
109
110
  //#region src/serialize.d.ts
111
+ /**
112
+ * Encoding levels determine what representation the RPC system hands to the transport.
113
+ * Each level names what the transport can assume about message values.
114
+ *
115
+ * - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
116
+ * - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
117
+ * - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
118
+ * - `"structuredClonable"`: Structured-clonable native values pass through where possible.
119
+ *
120
+ * @example
121
+ * ```ts
122
+ * // What happens to Uint8Array([1, 2, 3]) at each level:
123
+ * "string" → '["bytes","AQID"]' // JSON string with base64
124
+ * "jsonCompatible" → ["bytes", "AQID"] // JS array with base64
125
+ * "jsonCompatibleWithBytes" → ["bytes", Uint8Array] // JS array with raw bytes
126
+ * "structuredClonable" → ["bytes", Uint8Array] // + Date, BigInt stay native
127
+ * ```
128
+ */
129
+ type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
130
+ interface RpcLimits {
131
+ maxBigIntDigits: number;
132
+ maxDepth: number;
133
+ maxMessageSize: number;
134
+ }
135
+ declare const DEFAULT_MAX_DEPTH = 256;
136
+ declare const DEFAULT_LIMITS: RpcLimits;
110
137
  /**
111
138
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
112
139
  * RPC stubs, but it will support basic data types.
@@ -119,14 +146,21 @@ declare function deserialize(value: string): unknown;
119
146
  //#endregion
120
147
  //#region src/rpc.d.ts
121
148
  /**
122
- * Interface for an RPC transport, which is a simple bidirectional message stream. Implement this
123
- * interface if the built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
149
+ * Interface for a string-based RPC transport. This is the default transport type — no
150
+ * `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
151
+ * built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
124
152
  */
125
153
  interface RpcTransport {
126
154
  /**
127
- * Sends a message to the other end.
155
+ * The encoding level this transport works with. For this interface it is always "string";
156
+ * it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
128
157
  */
129
- send(message: string): Promise<void>;
158
+ readonly encodingLevel?: "string";
159
+ /**
160
+ * Sends a message to the other end. May optionally return a promise; if the promise rejects,
161
+ * the session is aborted.
162
+ */
163
+ send(message: string): void | Promise<void>;
130
164
  /**
131
165
  * Receives a message sent by the other end.
132
166
  *
@@ -145,6 +179,45 @@ interface RpcTransport {
145
179
  */
146
180
  abort?(reason: any): void;
147
181
  }
182
+ /**
183
+ * Interface for a transport that receives partially encoded JS values instead of JSON strings.
184
+ * The selected `encodingLevel` describes what the transport can assume about message values.
185
+ */
186
+ interface RpcTransportWithCustomEncoding {
187
+ /**
188
+ * The encoding level this transport works with.
189
+ *
190
+ * - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
191
+ * - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
192
+ * - "structuredClonable": Structured-clonable native values pass through where possible.
193
+ */
194
+ readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
195
+ /**
196
+ * Encodes and sends a message to the other end. Returns the encoded byte size if known.
197
+ * If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
198
+ * flow control. Send errors should be propagated via `receive()` rejecting.
199
+ */
200
+ send(message: unknown): number | void;
201
+ /**
202
+ * Receives and decodes a message sent by the other end.
203
+ *
204
+ * If and when the transport becomes disconnected, this will reject. The thrown error will be
205
+ * propagated to all outstanding calls and future calls on any stubs associated with the session.
206
+ * If there are no outstanding calls (and none are made in the future), then the error does not
207
+ * propagate anywhere -- this is considered a "clean" shutdown.
208
+ */
209
+ receive(): Promise<unknown>;
210
+ /**
211
+ * Indicates that the RPC system has suffered an error that prevents the session from continuing.
212
+ * The transport should ideally try to send any queued messages if it can, and then close the
213
+ * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
214
+ * before abort() is called is often an "abort" message, which communicates the error to the
215
+ * peer, so if that is dropped, the peer may have less information about what happened.)
216
+ */
217
+ abort?(reason: any): void;
218
+ }
219
+ /** Any supported transport type. */
220
+ type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
148
221
  /**
149
222
  * Options to customize behavior of an RPC session. All functions which start a session should
150
223
  * optionally accept this.
@@ -162,6 +235,16 @@ type RpcSessionOptions = {
162
235
  * to serialize the error with the stack omitted.
163
236
  */
164
237
  onSendError?: (error: Error) => Error | void;
238
+ /**
239
+ * Overrides for the resource limits enforced while deserializing messages from the peer. Any
240
+ * field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
241
+ * attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
242
+ *
243
+ * Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
244
+ * the peer never learns these values. A message that exceeds a limit is rejected, aborting the
245
+ * session.
246
+ */
247
+ limits?: Partial<RpcLimits>;
165
248
  };
166
249
  //#endregion
167
250
  //#region src/websocket.d.ts
@@ -170,6 +253,17 @@ type RpcSessionOptions = {
170
253
  * with the given `localMain`.
171
254
  */
172
255
  declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
256
+ /**
257
+ * Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
258
+ * `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
259
+ */
260
+ declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
261
+ #private;
262
+ constructor(webSocket: WebSocket);
263
+ send(message: T): void;
264
+ receive(): Promise<T>;
265
+ abort(reason: any): void;
266
+ }
173
267
  //#endregion
174
268
  //#region src/batch.d.ts
175
269
  /**
@@ -244,7 +338,7 @@ interface RpcSession<T extends RpcCompatible<T> = undefined> {
244
338
  drain(): Promise<void>;
245
339
  }
246
340
  declare const RpcSession: {
247
- new <T extends RpcCompatible<T> = undefined>(transport: RpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
341
+ new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
248
342
  };
249
343
  /**
250
344
  * Classes which are intended to be passed by reference and called over RPC must extend
@@ -297,7 +391,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
297
391
  * credentials as parameters and returns the authorized API), then cross-origin requests should
298
392
  * be safe.
299
393
  */
300
- declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
394
+ declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
301
395
  //#endregion
302
- export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
396
+ export { type AnyRpcTransport, DEFAULT_LIMITS, DEFAULT_MAX_DEPTH, type EncodingLevel, type RpcCompatible, type RpcLimits, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
303
397
  //# sourceMappingURL=index-workers.d.ts.map