capnweb 0.0.0-8a47045 → 0.0.0-92baaed
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.
- package/README.md +68 -3
- package/dist/index-bun.cjs +3105 -0
- package/dist/index-bun.cjs.map +1 -0
- package/dist/index-bun.d.cts +517 -0
- package/dist/index-bun.d.ts +517 -0
- package/dist/index-bun.js +3085 -0
- package/dist/index-bun.js.map +1 -0
- package/dist/index-workers.cjs +2914 -2547
- package/dist/index-workers.cjs.map +1 -1
- package/dist/index-workers.d.cts +396 -2
- package/dist/index-workers.d.ts +396 -2
- package/dist/index-workers.js +2877 -2520
- package/dist/index-workers.js.map +1 -1
- package/dist/index.cjs +2883 -2526
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +219 -187
- package/dist/index.d.ts +219 -187
- package/dist/index.js +2873 -2519
- package/dist/index.js.map +1 -1
- package/package.json +30 -18
package/dist/index.d.ts
CHANGED
|
@@ -1,131 +1,75 @@
|
|
|
1
|
-
import { IncomingMessage,
|
|
1
|
+
import { IncomingMessage, OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from "node:http";
|
|
2
2
|
|
|
3
|
+
//#region src/types.d.ts
|
|
3
4
|
// Copyright (c) 2025 Cloudflare, Inc.
|
|
4
5
|
// Licensed under the MIT license found in the LICENSE.txt file or at:
|
|
5
6
|
// https://opensource.org/license/mit
|
|
6
|
-
|
|
7
7
|
// This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
|
|
8
|
-
|
|
9
8
|
// Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
|
|
10
9
|
// TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
|
|
11
10
|
// For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
|
|
12
11
|
// accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
|
|
13
12
|
declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
|
|
14
13
|
declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
|
|
14
|
+
// Distinguishes mapper placeholders from regular values so param unwrapping can accept them.
|
|
15
|
+
declare const __RPC_MAP_VALUE_BRAND: unique symbol;
|
|
15
16
|
interface RpcTargetBranded {
|
|
16
17
|
[__RPC_TARGET_BRAND]: never;
|
|
17
18
|
}
|
|
18
|
-
|
|
19
19
|
// Types that can be used through `Stub`s
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
//
|
|
20
|
+
// `never[]` preserves compatibility with strongly-typed function signatures without introducing
|
|
21
|
+
// `any` into inference.
|
|
22
|
+
type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
|
|
23
|
+
type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false; // Types that can be passed over RPC
|
|
24
|
+
// The reason for using a generic type here is to build the serializable subset of RPC-compatible
|
|
25
|
+
// composite types. This allows types defined with the "interface" keyword to pass the
|
|
25
26
|
// serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
|
|
26
|
-
type RpcCompatible<T> =
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
T extends Map<unknown, infer U> ? RpcCompatible<U> : never
|
|
33
|
-
>
|
|
34
|
-
| Set<T extends Set<infer U> ? RpcCompatible<U> : never>
|
|
35
|
-
| Array<T extends Array<infer U> ? RpcCompatible<U> : never>
|
|
36
|
-
| ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
|
|
37
|
-
| {
|
|
38
|
-
[K in keyof T]: K extends number | string ? RpcCompatible<T[K]> : never;
|
|
39
|
-
}
|
|
40
|
-
| Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
|
|
41
|
-
// Special types
|
|
42
|
-
| Stub<Stubable>
|
|
43
|
-
// Serialized as stubs, see `Stubify`
|
|
44
|
-
| Stubable;
|
|
45
|
-
|
|
27
|
+
type RpcCompatible<T> = // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
|
|
28
|
+
(IsUnknown<T> extends true ? unknown : never) // RPC-compatible base values
|
|
29
|
+
| BaseType // RPC-compatible composites
|
|
30
|
+
| Map<T extends Map<infer U, unknown> ? RpcCompatible<U> : never, T extends Map<unknown, infer U> ? RpcCompatible<U> : never> | Set<T extends Set<infer U> ? RpcCompatible<U> : never> | Array<T extends Array<infer U> ? RpcCompatible<U> : never> | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never> | { [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]> } | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never> // Special types
|
|
31
|
+
| Stub<Stubable> // Serialized as stubs, see `Stubify`
|
|
32
|
+
| Stubable;
|
|
46
33
|
// Base type for all RPC stubs, including common memory management methods.
|
|
47
34
|
// `T` is used as a marker type for unwrapping `Stub`s later.
|
|
48
|
-
interface StubBase<T
|
|
35
|
+
interface StubBase<T = unknown> extends Disposable {
|
|
49
36
|
[__RPC_STUB_BRAND]: T;
|
|
50
37
|
dup(): this;
|
|
51
38
|
onRpcBroken(callback: (error: any) => void): void;
|
|
52
39
|
}
|
|
53
|
-
type Stub<T extends RpcCompatible<T>> =
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
| Uint8Array
|
|
58
|
-
| Uint8ClampedArray
|
|
59
|
-
| Uint16Array
|
|
60
|
-
| Uint32Array
|
|
61
|
-
| Int8Array
|
|
62
|
-
| Int16Array
|
|
63
|
-
| Int32Array
|
|
64
|
-
| BigUint64Array
|
|
65
|
-
| BigInt64Array
|
|
66
|
-
| Float32Array
|
|
67
|
-
| Float64Array;
|
|
68
|
-
|
|
69
|
-
// This represents all the types that can be sent as-is over an RPC boundary
|
|
70
|
-
type BaseType =
|
|
71
|
-
| void
|
|
72
|
-
| undefined
|
|
73
|
-
| null
|
|
74
|
-
| boolean
|
|
75
|
-
| number
|
|
76
|
-
| bigint
|
|
77
|
-
| string
|
|
78
|
-
| TypedArray
|
|
79
|
-
| ArrayBuffer
|
|
80
|
-
| DataView
|
|
81
|
-
| Date
|
|
82
|
-
| Error
|
|
83
|
-
| RegExp
|
|
84
|
-
| ReadableStream<Uint8Array>
|
|
85
|
-
| WritableStream<Uint8Array>
|
|
86
|
-
| Request
|
|
87
|
-
| Response
|
|
88
|
-
| Headers;
|
|
89
|
-
// Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
|
|
40
|
+
type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
|
|
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
|
|
43
|
+
| Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
|
|
90
44
|
// prettier-ignore
|
|
91
|
-
type Stubify<T> =
|
|
92
|
-
|
|
93
|
-
:
|
|
94
|
-
|
|
95
|
-
: T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
|
|
96
|
-
: T extends Set<infer V> ? Set<Stubify<V>>
|
|
97
|
-
: T extends Array<infer V> ? Array<Stubify<V>>
|
|
98
|
-
: T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
|
|
99
|
-
: T extends BaseType ? T
|
|
100
|
-
// When using "unknown" instead of "any", interfaces are not stubified.
|
|
101
|
-
: T extends { [key: string | number]: any } ? { [K in keyof T]: Stubify<T[K]> }
|
|
102
|
-
: T;
|
|
103
|
-
|
|
45
|
+
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.
|
|
46
|
+
: T extends {
|
|
47
|
+
[key: string | number]: any;
|
|
48
|
+
} ? { [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]> } : T;
|
|
104
49
|
// Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
|
|
105
50
|
// Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
|
|
106
51
|
// `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
|
|
107
52
|
// prettier-ignore
|
|
108
|
-
type UnstubifyInner<T> =
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
:
|
|
112
|
-
|
|
113
|
-
: T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
|
|
114
|
-
: T extends BaseType ? T
|
|
115
|
-
: T extends { [key: string | number]: unknown } ? { [K in keyof T]: Unstubify<T[K]> }
|
|
116
|
-
: T;
|
|
117
|
-
|
|
118
|
-
// You can put promises anywhere in the params and they'll be resolved before delivery.
|
|
53
|
+
type UnstubifyInner<T> = // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
|
|
54
|
+
// is already assignable to the value type (important for callback contextual typing).
|
|
55
|
+
T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>)) : T extends Promise<infer U> ? UnstubifyInner<U> : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>> : T extends Set<infer V> ? Set<Unstubify<V>> : T extends [] ? [] : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>] : T extends readonly [] ? readonly [] : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>] : T extends Array<infer V> ? Array<Unstubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>> : T extends BaseType ? T : T extends {
|
|
56
|
+
[key: string | number]: unknown;
|
|
57
|
+
} ? { [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]> } : T; // You can put promises anywhere in the params and they'll be resolved before delivery.
|
|
119
58
|
// (This also covers RpcPromise, because it's defined as being a Promise.)
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
//
|
|
59
|
+
// Map placeholders are also allowed so primitive map callback inputs can be forwarded directly
|
|
60
|
+
// into RPC params.
|
|
61
|
+
//
|
|
62
|
+
// Keep raw non-stub members so generic assignability still works when UnstubifyInner<T> is deferred.
|
|
63
|
+
// Remove stub members from mixed unions so callback params don’t get both stub and unstubbed signatures.
|
|
64
|
+
// Marker carried by map() callback inputs. This lets primitive placeholders flow through params.
|
|
65
|
+
type Unstubify<T> = NonStubMembers<T> | UnstubifyInner<T> | Promise<UnstubifyInner<T>> | MapValuePlaceholder<UnstubifyInner<T>>;
|
|
66
|
+
type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
|
|
67
|
+
interface MapValuePlaceholder<T> {
|
|
68
|
+
[__RPC_MAP_VALUE_BRAND]: T;
|
|
69
|
+
}
|
|
70
|
+
type NonStubMembers<T> = Exclude<T, StubBase<any>>; // Utility type for adding `Disposable`s to `object` types only.
|
|
125
71
|
// Note `unknown & T` is equivalent to `T`.
|
|
126
|
-
type MaybeDisposable<T> = T extends object ? Disposable : unknown;
|
|
127
|
-
|
|
128
|
-
// Type for method return or property on an RPC interface.
|
|
72
|
+
type MaybeDisposable<T> = T extends object ? Disposable : unknown; // Type for method return or property on an RPC interface.
|
|
129
73
|
// - Stubable types are replaced by stubs.
|
|
130
74
|
// - RpcCompatible types are passed by value, with stubable types replaced by stubs
|
|
131
75
|
// and a top-level `Disposer`.
|
|
@@ -133,44 +77,62 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
|
|
|
133
77
|
// Technically, we use custom thenables here, but they quack like `Promise`s.
|
|
134
78
|
// Intersecting with `(Maybe)Provider` allows pipelining.
|
|
135
79
|
// prettier-ignore
|
|
136
|
-
type Result<R> =
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
: never;
|
|
140
|
-
|
|
141
|
-
// Type for method or property on an RPC interface.
|
|
80
|
+
type Result<R> = IsAny<R> extends true ? UnknownResult : IsUnknown<R> extends true ? UnknownResult : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R> : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R> : never;
|
|
81
|
+
type IsAny<T> = 0 extends (1 & T) ? true : false;
|
|
82
|
+
type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>; // Type for method or property on an RPC interface.
|
|
142
83
|
// For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
|
|
143
84
|
// Unwrapping `Stub`s allows calling with `Stubable` arguments.
|
|
144
85
|
// For properties, rewrite types to be `Result`s.
|
|
145
86
|
// In each case, unwrap `Promise`s.
|
|
146
|
-
type MethodOrProperty<V> = V extends (...args: infer P) => infer R
|
|
147
|
-
? (...args: UnstubifyAll<P>) => Result<Awaited<R>>
|
|
148
|
-
: Result<Awaited<V>>;
|
|
149
|
-
|
|
150
|
-
// Type for the callable part of an `Provider` if `T` is callable.
|
|
87
|
+
type MethodOrProperty<V> = V extends ((...args: infer P) => infer R) ? (...args: UnstubifyAll<P>) => IsAny<R> extends true ? UnknownResult : Result<Awaited<R>> : Result<Awaited<V>>; // Type for the callable part of an `Provider` if `T` is callable.
|
|
151
88
|
// This is intersected with methods/properties.
|
|
152
|
-
type MaybeCallableProvider<T> = T extends (...args: any[]) => any
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
89
|
+
type MaybeCallableProvider<T> = T extends ((...args: any[]) => any) ? MethodOrProperty<T> : unknown;
|
|
90
|
+
type TupleIndexKeys<T extends ReadonlyArray<unknown>> = Extract<keyof T, `${number}`>;
|
|
91
|
+
type MapCallbackValue<T> = // `Omit` removes call signatures, so re-intersect callable provider behavior.
|
|
92
|
+
T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> & MapValuePlaceholder<T> : never;
|
|
93
|
+
type InvalidNativePromiseInMapResult<T, Seen = never> = T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
|
|
94
|
+
type InvalidNativePromiseInMapResultImpl<T, Seen> = [T] extends [Seen] ? never // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
|
|
95
|
+
: T extends StubBase<any> ? never // Native thenables cannot be represented in map recordings, even when typed as PromiseLike.
|
|
96
|
+
: T extends PromiseLike<unknown> ? T : T extends Map<infer K, infer V> ? InvalidNativePromiseInMapResult<K, Seen | T> | InvalidNativePromiseInMapResult<V, Seen | T> : T extends Set<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T> : T extends readonly [] ? never : T extends readonly [infer Head, ...infer Tail] ? InvalidNativePromiseInMapResult<Head, Seen | T> | InvalidNativePromiseInMapResult<Tail[number], Seen | T> : T extends ReadonlyArray<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T> : T extends {
|
|
97
|
+
[key: string | number]: unknown;
|
|
98
|
+
} ? InvalidNativePromiseInMapResult<T[Extract<keyof T, string | number>], Seen | T> : never;
|
|
99
|
+
type MapCallbackReturn<T> = InvalidNativePromiseInMapResult<T> extends never ? T : never;
|
|
100
|
+
type ArrayProvider<E> = { [K in number]: MethodOrProperty<E> } & {
|
|
101
|
+
map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<V>): Result<Array<V>>;
|
|
102
|
+
};
|
|
103
|
+
type TupleProvider<T extends ReadonlyArray<unknown>> = { [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]> } & ArrayProvider<T[number]>; // Base type for all other types providing RPC-like interfaces.
|
|
157
104
|
// Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
|
|
158
|
-
type Provider<T> = MaybeCallableProvider<T> &
|
|
159
|
-
(T
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
105
|
+
type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown> ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T> : { [K in Exclude<keyof T, symbol | keyof StubBase<never>>]: MethodOrProperty<T[K]> } & {
|
|
106
|
+
map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
|
|
107
|
+
});
|
|
108
|
+
//#endregion
|
|
109
|
+
//#region src/serialize.d.ts
|
|
110
|
+
/**
|
|
111
|
+
* Encoding levels determine what representation the RPC system hands to the transport.
|
|
112
|
+
* Each level names what the transport can assume about message values.
|
|
113
|
+
*
|
|
114
|
+
* - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
|
|
115
|
+
* - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
|
|
116
|
+
* - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
|
|
117
|
+
* - `"structuredClonable"`: Structured-clonable native values pass through where possible.
|
|
118
|
+
*
|
|
119
|
+
* @example
|
|
120
|
+
* ```ts
|
|
121
|
+
* // What happens to Uint8Array([1, 2, 3]) at each level:
|
|
122
|
+
* "string" → '["bytes","AQID"]' // JSON string with base64
|
|
123
|
+
* "jsonCompatible" → ["bytes", "AQID"] // JS array with base64
|
|
124
|
+
* "jsonCompatibleWithBytes" → ["bytes", Uint8Array] // JS array with raw bytes
|
|
125
|
+
* "structuredClonable" → ["bytes", Uint8Array] // + Date, BigInt stay native
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
|
|
129
|
+
interface RpcLimits {
|
|
130
|
+
maxBigIntDigits: number;
|
|
131
|
+
maxDepth: number;
|
|
132
|
+
maxMessageSize: number;
|
|
133
|
+
}
|
|
134
|
+
declare const DEFAULT_MAX_DEPTH = 256;
|
|
135
|
+
declare const DEFAULT_LIMITS: RpcLimits;
|
|
174
136
|
/**
|
|
175
137
|
* Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
|
|
176
138
|
* RPC stubs, but it will support basic data types.
|
|
@@ -180,59 +142,129 @@ declare function serialize(value: unknown): string;
|
|
|
180
142
|
* Deserialize a value serialized using serialize().
|
|
181
143
|
*/
|
|
182
144
|
declare function deserialize(value: string): unknown;
|
|
183
|
-
|
|
145
|
+
//#endregion
|
|
146
|
+
//#region src/rpc.d.ts
|
|
184
147
|
/**
|
|
185
|
-
* Interface for
|
|
186
|
-
*
|
|
148
|
+
* Interface for a string-based RPC transport. This is the default transport type — no
|
|
149
|
+
* `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
|
|
150
|
+
* built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
|
|
187
151
|
*/
|
|
188
152
|
interface RpcTransport {
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
153
|
+
/**
|
|
154
|
+
* The encoding level this transport works with. For this interface it is always "string";
|
|
155
|
+
* it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
|
|
156
|
+
*/
|
|
157
|
+
readonly encodingLevel?: "string";
|
|
158
|
+
/**
|
|
159
|
+
* Sends a message to the other end. May optionally return a promise; if the promise rejects,
|
|
160
|
+
* the session is aborted.
|
|
161
|
+
*/
|
|
162
|
+
send(message: string): void | Promise<void>;
|
|
163
|
+
/**
|
|
164
|
+
* Receives a message sent by the other end.
|
|
165
|
+
*
|
|
166
|
+
* If and when the transport becomes disconnected, this will reject. The thrown error will be
|
|
167
|
+
* propagated to all outstanding calls and future calls on any stubs associated with the session.
|
|
168
|
+
* If there are no outstanding calls (and none are made in the future), then the error does not
|
|
169
|
+
* propagate anywhere -- this is considered a "clean" shutdown.
|
|
170
|
+
*/
|
|
171
|
+
receive(): Promise<string>;
|
|
172
|
+
/**
|
|
173
|
+
* Indicates that the RPC system has suffered an error that prevents the session from continuing.
|
|
174
|
+
* The transport should ideally try to send any queued messages if it can, and then close the
|
|
175
|
+
* connection. (It's not strictly necessary to deliver queued messages, but the last message sent
|
|
176
|
+
* before abort() is called is often an "abort" message, which communicates the error to the
|
|
177
|
+
* peer, so if that is dropped, the peer may have less information about what happened.)
|
|
178
|
+
*/
|
|
179
|
+
abort?(reason: any): void;
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Interface for a transport that receives partially encoded JS values instead of JSON strings.
|
|
183
|
+
* The selected `encodingLevel` describes what the transport can assume about message values.
|
|
184
|
+
*/
|
|
185
|
+
interface RpcTransportWithCustomEncoding {
|
|
186
|
+
/**
|
|
187
|
+
* The encoding level this transport works with.
|
|
188
|
+
*
|
|
189
|
+
* - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
|
|
190
|
+
* - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
|
|
191
|
+
* - "structuredClonable": Structured-clonable native values pass through where possible.
|
|
192
|
+
*/
|
|
193
|
+
readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
|
|
194
|
+
/**
|
|
195
|
+
* Encodes and sends a message to the other end. Returns the encoded byte size if known.
|
|
196
|
+
* If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
|
|
197
|
+
* flow control. Send errors should be propagated via `receive()` rejecting.
|
|
198
|
+
*/
|
|
199
|
+
send(message: unknown): number | void;
|
|
200
|
+
/**
|
|
201
|
+
* Receives and decodes a message sent by the other end.
|
|
202
|
+
*
|
|
203
|
+
* If and when the transport becomes disconnected, this will reject. The thrown error will be
|
|
204
|
+
* propagated to all outstanding calls and future calls on any stubs associated with the session.
|
|
205
|
+
* If there are no outstanding calls (and none are made in the future), then the error does not
|
|
206
|
+
* propagate anywhere -- this is considered a "clean" shutdown.
|
|
207
|
+
*/
|
|
208
|
+
receive(): Promise<unknown>;
|
|
209
|
+
/**
|
|
210
|
+
* Indicates that the RPC system has suffered an error that prevents the session from continuing.
|
|
211
|
+
* The transport should ideally try to send any queued messages if it can, and then close the
|
|
212
|
+
* connection. (It's not strictly necessary to deliver queued messages, but the last message sent
|
|
213
|
+
* before abort() is called is often an "abort" message, which communicates the error to the
|
|
214
|
+
* peer, so if that is dropped, the peer may have less information about what happened.)
|
|
215
|
+
*/
|
|
216
|
+
abort?(reason: any): void;
|
|
210
217
|
}
|
|
218
|
+
/** Any supported transport type. */
|
|
219
|
+
type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
|
|
211
220
|
/**
|
|
212
221
|
* Options to customize behavior of an RPC session. All functions which start a session should
|
|
213
222
|
* optionally accept this.
|
|
214
223
|
*/
|
|
215
224
|
type RpcSessionOptions = {
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
225
|
+
/**
|
|
226
|
+
* If provided, this function will be called whenever an `Error` object is serialized (for any
|
|
227
|
+
* reason, not just because it was thrown). This can be used to log errors, and also to redact
|
|
228
|
+
* them.
|
|
229
|
+
*
|
|
230
|
+
* If `onSendError` returns an Error object, than object will be substituted in place of the
|
|
231
|
+
* original. If it has a stack property, the stack will be sent to the client.
|
|
232
|
+
*
|
|
233
|
+
* If `onSendError` doesn't return anything (or is not provided at all), the default behavior is
|
|
234
|
+
* to serialize the error with the stack omitted.
|
|
235
|
+
*/
|
|
236
|
+
onSendError?: (error: Error) => Error | void;
|
|
237
|
+
/**
|
|
238
|
+
* Overrides for the resource limits enforced while deserializing messages from the peer. Any
|
|
239
|
+
* field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
|
|
240
|
+
* attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
|
|
241
|
+
*
|
|
242
|
+
* Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
|
|
243
|
+
* the peer never learns these values. A message that exceeds a limit is rejected, aborting the
|
|
244
|
+
* session.
|
|
245
|
+
*/
|
|
246
|
+
limits?: Partial<RpcLimits>;
|
|
228
247
|
};
|
|
229
|
-
|
|
248
|
+
//#endregion
|
|
249
|
+
//#region src/websocket.d.ts
|
|
230
250
|
/**
|
|
231
251
|
* For use in Cloudflare Workers: Construct an HTTP response that starts a WebSocket RPC session
|
|
232
252
|
* with the given `localMain`.
|
|
233
253
|
*/
|
|
234
254
|
declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
|
|
235
|
-
|
|
255
|
+
/**
|
|
256
|
+
* Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
|
|
257
|
+
* `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
|
|
258
|
+
*/
|
|
259
|
+
declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
|
|
260
|
+
#private;
|
|
261
|
+
constructor(webSocket: WebSocket);
|
|
262
|
+
send(message: T): void;
|
|
263
|
+
receive(): Promise<T>;
|
|
264
|
+
abort(reason: any): void;
|
|
265
|
+
}
|
|
266
|
+
//#endregion
|
|
267
|
+
//#region src/batch.d.ts
|
|
236
268
|
/**
|
|
237
269
|
* Implements the server end of an HTTP batch session, using standard Fetch API types to represent
|
|
238
270
|
* HTTP requests and responses.
|
|
@@ -253,9 +285,10 @@ declare function newHttpBatchRpcResponse(request: Request, localMain: any, optio
|
|
|
253
285
|
* @param options Optional RPC session options. You can also pass headers to set on the response.
|
|
254
286
|
*/
|
|
255
287
|
declare function nodeHttpBatchRpcResponse(request: IncomingMessage, response: ServerResponse, localMain: any, options?: RpcSessionOptions & {
|
|
256
|
-
|
|
288
|
+
headers?: OutgoingHttpHeaders | OutgoingHttpHeader[];
|
|
257
289
|
}): Promise<void>;
|
|
258
|
-
|
|
290
|
+
//#endregion
|
|
291
|
+
//#region src/index.d.ts
|
|
259
292
|
/**
|
|
260
293
|
* Represents a reference to a remote object, on which methods may be remotely invoked via RPC.
|
|
261
294
|
*
|
|
@@ -268,7 +301,7 @@ declare function nodeHttpBatchRpcResponse(request: IncomingMessage, response: Se
|
|
|
268
301
|
*/
|
|
269
302
|
type RpcStub<T extends RpcCompatible<T>> = Stub<T>;
|
|
270
303
|
declare const RpcStub: {
|
|
271
|
-
|
|
304
|
+
new <T extends RpcCompatible<T>>(value: T): RpcStub<T>;
|
|
272
305
|
};
|
|
273
306
|
/**
|
|
274
307
|
* Represents the result of an RPC call.
|
|
@@ -296,15 +329,15 @@ declare const RpcPromise: {};
|
|
|
296
329
|
* Most people won't use this. You only need it if you've implemented your own `RpcTransport`.
|
|
297
330
|
*/
|
|
298
331
|
interface RpcSession<T extends RpcCompatible<T> = undefined> {
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
332
|
+
getRemoteMain(): RpcStub<T>;
|
|
333
|
+
getStats(): {
|
|
334
|
+
imports: number;
|
|
335
|
+
exports: number;
|
|
336
|
+
};
|
|
337
|
+
drain(): Promise<void>;
|
|
305
338
|
}
|
|
306
339
|
declare const RpcSession: {
|
|
307
|
-
|
|
340
|
+
new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
|
|
308
341
|
};
|
|
309
342
|
/**
|
|
310
343
|
* Classes which are intended to be passed by reference and called over RPC must extend
|
|
@@ -314,17 +347,15 @@ declare const RpcSession: {
|
|
|
314
347
|
* Note that on Cloudflare Workers, this `RpcTarget` is an alias for the one exported from the
|
|
315
348
|
* "cloudflare:workers" module, so they can be used interchangably.
|
|
316
349
|
*/
|
|
317
|
-
interface RpcTarget extends RpcTargetBranded {
|
|
318
|
-
}
|
|
350
|
+
interface RpcTarget extends RpcTargetBranded {}
|
|
319
351
|
declare const RpcTarget: {
|
|
320
|
-
|
|
352
|
+
new (): RpcTarget;
|
|
321
353
|
};
|
|
322
354
|
/**
|
|
323
355
|
* Empty interface used as default type parameter for sessions where the other side doesn't
|
|
324
356
|
* necessarily export a main interface.
|
|
325
357
|
*/
|
|
326
|
-
interface Empty {
|
|
327
|
-
}
|
|
358
|
+
interface Empty {}
|
|
328
359
|
/**
|
|
329
360
|
* Start a WebSocket session given either an already-open WebSocket or a URL.
|
|
330
361
|
*
|
|
@@ -359,6 +390,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
|
|
|
359
390
|
* credentials as parameters and returns the authorized API), then cross-origin requests should
|
|
360
391
|
* be safe.
|
|
361
392
|
*/
|
|
362
|
-
declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
|
|
363
|
-
|
|
364
|
-
export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
|
|
393
|
+
declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
|
|
394
|
+
//#endregion
|
|
395
|
+
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 };
|
|
396
|
+
//# sourceMappingURL=index.d.ts.map
|