capnweb 0.0.0-43aa384 → 0.0.0-46de5a7

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 CHANGED
@@ -203,6 +203,7 @@ The following types can be passed over RPC (in arguments or return values), and
203
203
  * `Error` and its well-known subclasses
204
204
  * `Blob`
205
205
  * `ReadableStream` and `WritableStream`, with automatic flow control.
206
+ * `URL`
206
207
  * `Headers`, `Request`, and `Response` from the Fetch API.
207
208
 
208
209
  The following types are not supported as of this writing, but may be added in the future:
@@ -378,6 +379,40 @@ Sometimes you need to pass a stub somewhere where it will be disposed, but also
378
379
 
379
380
  Hint: You can call `.dup()` on a property of a stub or promise, in order to create a stub backed by that property. This is particularly useful when you know in advance that the property is going to resolve to a stub: calling `.dup()` on it gives you a stub you can start using immediately, that otherwise behaves exactly the same as the eventual stub would if you awaited it.
380
381
 
382
+ #### Holding on to a callback past the call that delivered it
383
+
384
+ A common bidirectional-calling pattern is for the client to pass a callback to the server, which the server then invokes later (for example from a timer, an event handler, or a subsequent RPC). Because the callback parameter is a stub, and stubs in params are implicitly disposed when the call returns, the server must duplicate the stub with `.dup()` if it wants to invoke the callback after the call completes:
385
+
386
+ ```ts
387
+ import { type RpcStub, RpcTarget } from 'capnweb';
388
+
389
+ // A callback the client passes in: a stub wrapping a function.
390
+ type Listener = RpcStub<(msg: string) => void>;
391
+
392
+ class Api extends RpcTarget {
393
+ #listener?: Listener;
394
+
395
+ // Stubs passed as params are disposed when the call returns, so `.dup()`
396
+ // to keep a reference that outlives registerListener().
397
+ registerListener(listener: Listener) {
398
+ this.#listener?.[Symbol.dispose](); // release any previous listener
399
+ this.#listener = listener.dup();
400
+ }
401
+
402
+ // A *later* call can invoke the retained callback -- still valid thanks to .dup().
403
+ notify(msg: string) {
404
+ this.#listener?.(msg);
405
+ }
406
+
407
+ // Dispose our duplicate when done so the client-side stub can be freed.
408
+ [Symbol.dispose]() {
409
+ this.#listener?.[Symbol.dispose]();
410
+ }
411
+ }
412
+ ```
413
+
414
+ The same rule applies in the other direction: if the server returns a stub to the client and the client wants to keep using it after disposing the result, the client should `.dup()` the stub before the result is disposed.
415
+
381
416
  ### Listening for disposal
382
417
 
383
418
  An `RpcTarget` may declare a `Symbol.dispose` method. If it does, the RPC system will automatically invoke it when a stub pointing at it (and all its duplicates) has been disposed.
@@ -58,6 +58,7 @@ function typeForRpc(value) {
58
58
  case Float64Array.prototype: return "bytes";
59
59
  case WritableStream.prototype: return "writable";
60
60
  case ReadableStream.prototype: return "readable";
61
+ case URL.prototype: return "url";
61
62
  case Headers.prototype: return "headers";
62
63
  case Request.prototype: return "request";
63
64
  case Response.prototype: return "response";
@@ -91,7 +92,14 @@ let streamImpl = {
91
92
  };
92
93
  var StubHook = class {
93
94
  stream(path, args) {
94
- let pulled = this.call(path, args).pull();
95
+ let hook = this.call(path, args);
96
+ let pulled;
97
+ try {
98
+ pulled = hook.pull();
99
+ } catch (err) {
100
+ hook.dispose();
101
+ throw err;
102
+ }
95
103
  let promise;
96
104
  if (pulled instanceof Promise) promise = pulled.then((p) => {
97
105
  p.dispose();
@@ -110,9 +118,11 @@ var ErrorStubHook = class extends StubHook {
110
118
  this.error = error;
111
119
  }
112
120
  call(path, args) {
121
+ args.dispose();
113
122
  return this;
114
123
  }
115
124
  map(path, captures, instructions) {
125
+ for (let cap of captures) cap.dispose();
116
126
  return this;
117
127
  }
118
128
  get(path) {
@@ -392,6 +402,7 @@ var RpcPayload = class RpcPayload {
392
402
  case "date":
393
403
  case "bytes":
394
404
  case "blob":
405
+ case "url":
395
406
  case "error":
396
407
  case "undefined": return value;
397
408
  case "array": {
@@ -589,6 +600,7 @@ var RpcPayload = class RpcPayload {
589
600
  case "bytes":
590
601
  case "blob":
591
602
  case "date":
603
+ case "url":
592
604
  case "error":
593
605
  case "undefined": return;
594
606
  case "array": {
@@ -671,6 +683,7 @@ var RpcPayload = class RpcPayload {
671
683
  case "rpc-target":
672
684
  case "writable":
673
685
  case "readable":
686
+ case "url":
674
687
  case "headers":
675
688
  case "request":
676
689
  case "response": return;
@@ -740,6 +753,7 @@ function followPath(value, parent, path, owner) {
740
753
  case "blob":
741
754
  case "date":
742
755
  case "error":
756
+ case "url":
743
757
  case "headers":
744
758
  case "request":
745
759
  case "response":
@@ -772,17 +786,22 @@ function followPath(value, parent, path, owner) {
772
786
  }
773
787
  var ValueStubHook = class extends StubHook {
774
788
  call(path, args) {
789
+ let followResult;
775
790
  try {
776
791
  let { value, owner } = this.getValue();
777
- let followResult = followPath(value, void 0, path, owner);
778
- if (followResult.hook) return followResult.hook.call(followResult.remainingPath, args);
779
- if (typeof followResult.value != "function") throw new TypeError(`'${path.join(".")}' is not a function.`);
780
- return new PromiseStubHook(args.deliverCall(followResult.value, followResult.parent).then((payload) => {
781
- return new PayloadStubHook(payload);
782
- }));
792
+ followResult = followPath(value, void 0, path, owner);
783
793
  } catch (err) {
794
+ args.dispose();
784
795
  return new ErrorStubHook(err);
785
796
  }
797
+ if (followResult.hook) return followResult.hook.call(followResult.remainingPath, args);
798
+ if (typeof followResult.value != "function") {
799
+ args.dispose();
800
+ return new ErrorStubHook(/* @__PURE__ */ new TypeError(`'${path.join(".")}' is not a function.`));
801
+ }
802
+ return new PromiseStubHook(args.deliverCall(followResult.value, followResult.parent).then((payload) => {
803
+ return new PayloadStubHook(payload);
804
+ }));
786
805
  }
787
806
  map(path, captures, instructions) {
788
807
  try {
@@ -920,12 +939,16 @@ var PromiseStubHook = class PromiseStubHook extends StubHook {
920
939
  }
921
940
  call(path, args) {
922
941
  args.ensureDeepCopied();
923
- return new PromiseStubHook(this.promise.then((hook) => hook.call(path, args)));
942
+ return new PromiseStubHook(this.promise.then((hook) => hook.call(path, args), (err) => {
943
+ args.dispose();
944
+ throw err;
945
+ }));
924
946
  }
925
947
  stream(path, args) {
926
948
  args.ensureDeepCopied();
927
- return { promise: this.promise.then((hook) => {
928
- return hook.stream(path, args).promise;
949
+ return { promise: this.promise.then((hook) => hook.stream(path, args).promise, (err) => {
950
+ args.dispose();
951
+ throw err;
929
952
  }) };
930
953
  }
931
954
  map(path, captures, instructions) {
@@ -952,10 +975,7 @@ var PromiseStubHook = class PromiseStubHook extends StubHook {
952
975
  }, (err) => {});
953
976
  }
954
977
  dispose() {
955
- if (this.resolution) this.resolution.dispose();
956
- else this.promise.then((hook) => {
957
- hook.dispose();
958
- }, (err) => {});
978
+ this.promise.then((hook) => hook.dispose(), () => {});
959
979
  }
960
980
  onBroken(callback) {
961
981
  if (this.resolution) this.resolution.onBroken(callback);
@@ -1162,6 +1182,7 @@ var Devaluator = class Devaluator {
1162
1182
  alternateTypeName
1163
1183
  ];
1164
1184
  }
1185
+ case "url": return ["url", value.href];
1165
1186
  case "headers": return ["headers", [...value]];
1166
1187
  case "request": {
1167
1188
  let req = value;
@@ -1481,6 +1502,9 @@ var Evaluator = class Evaluator {
1481
1502
  case "inf": return Infinity;
1482
1503
  case "-inf": return -Infinity;
1483
1504
  case "nan": return NaN;
1505
+ case "url":
1506
+ if (value.length === 2 && typeof value[1] === "string") return new URL(value[1]);
1507
+ break;
1484
1508
  case "headers":
1485
1509
  if (value.length === 2 && value[1] instanceof Array) return new Headers(value[1]);
1486
1510
  break;
@@ -1780,24 +1804,28 @@ var RpcImportHook = class RpcImportHook extends StubHook {
1780
1804
  if (this.entry) return this.entry;
1781
1805
  else throw new Error("This RpcImportHook was already disposed.");
1782
1806
  }
1807
+ getEntryTakingOwnership(disposeOwned) {
1808
+ try {
1809
+ return this.getEntry();
1810
+ } catch (err) {
1811
+ disposeOwned();
1812
+ throw err;
1813
+ }
1814
+ }
1783
1815
  call(path, args) {
1784
- let entry = this.getEntry();
1816
+ let entry = this.getEntryTakingOwnership(() => args.dispose());
1785
1817
  if (entry.resolution) return entry.resolution.call(path, args);
1786
1818
  else return entry.session.sendCall(entry.importId, path, args);
1787
1819
  }
1788
1820
  stream(path, args) {
1789
- let entry = this.getEntry();
1821
+ let entry = this.getEntryTakingOwnership(() => args.dispose());
1790
1822
  if (entry.resolution) return entry.resolution.stream(path, args);
1791
1823
  else return entry.session.sendStream(entry.importId, path, args);
1792
1824
  }
1793
1825
  map(path, captures, instructions) {
1794
- let entry;
1795
- try {
1796
- entry = this.getEntry();
1797
- } catch (err) {
1826
+ let entry = this.getEntryTakingOwnership(() => {
1798
1827
  for (let cap of captures) cap.dispose();
1799
- throw err;
1800
- }
1828
+ });
1801
1829
  if (entry.resolution) return entry.resolution.map(path, captures, instructions);
1802
1830
  else return entry.session.sendMap(entry.importId, path, captures, instructions);
1803
1831
  }
@@ -2058,14 +2086,23 @@ var RpcSessionImpl = class {
2058
2086
  }
2059
2087
  }
2060
2088
  sendCall(id, path, args) {
2061
- if (this.abortReason) throw this.abortReason;
2089
+ if (this.abortReason) {
2090
+ args?.dispose();
2091
+ throw this.abortReason;
2092
+ }
2062
2093
  let value = [
2063
2094
  "pipeline",
2064
2095
  id,
2065
2096
  path
2066
2097
  ];
2067
2098
  if (args) {
2068
- let devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
2099
+ let devalue;
2100
+ try {
2101
+ devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
2102
+ } catch (err) {
2103
+ args.dispose();
2104
+ throw err;
2105
+ }
2069
2106
  value.push(devalue[0]);
2070
2107
  }
2071
2108
  this.send(["push", value]);
@@ -2074,13 +2111,22 @@ var RpcSessionImpl = class {
2074
2111
  return new RpcImportHook(true, entry);
2075
2112
  }
2076
2113
  sendStream(id, path, args) {
2077
- if (this.abortReason) throw this.abortReason;
2114
+ if (this.abortReason) {
2115
+ args.dispose();
2116
+ throw this.abortReason;
2117
+ }
2078
2118
  let value = [
2079
2119
  "pipeline",
2080
2120
  id,
2081
2121
  path
2082
2122
  ];
2083
- let devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
2123
+ let devalue;
2124
+ try {
2125
+ devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
2126
+ } catch (err) {
2127
+ args.dispose();
2128
+ throw err;
2129
+ }
2084
2130
  value.push(devalue[0]);
2085
2131
  let msg = ["stream", value];
2086
2132
  let size = this.send(msg);
@@ -2301,7 +2347,7 @@ var RpcSession$1 = class {
2301
2347
 
2302
2348
  //#endregion
2303
2349
  //#region src/websocket.ts
2304
- /** Close-frame reason max UTF-8 bytes: 125 payload − 2-byte status (RFC 6455 §5.5). */
2350
+ /** Close-frame reason max UTF-8 bytes: 125 payload - 2-byte status (RFC 6455 section 5.5). */
2305
2351
  const MAX_CLOSE_REASON_BYTES = 123;
2306
2352
  function newWebSocketRpcSession$1(webSocket, localMain, options) {
2307
2353
  if (typeof webSocket === "string") webSocket = new WebSocket(webSocket);
@@ -2711,9 +2757,11 @@ var MapVariableHook = class extends StubHook {
2711
2757
  else throwMapperBuilderUseError();
2712
2758
  }
2713
2759
  call(path, args) {
2760
+ args.dispose();
2714
2761
  throwMapperBuilderUseError();
2715
2762
  }
2716
2763
  map(path, captures, instructions) {
2764
+ for (let cap of captures) cap.dispose();
2717
2765
  throwMapperBuilderUseError();
2718
2766
  }
2719
2767
  pull() {
@@ -2824,13 +2872,11 @@ var WritableStreamStubHook = class WritableStreamStubHook extends StubHook {
2824
2872
  let state = this.getState();
2825
2873
  if (path.length !== 1 || typeof path[0] !== "string") throw new Error("WritableStream stub only supports direct method calls");
2826
2874
  const method = path[0];
2827
- if (method !== "write" && method !== "close" && method !== "abort") {
2828
- args.dispose();
2829
- throw new Error(`Unknown WritableStream method: ${method}`);
2830
- }
2875
+ if (method !== "write" && method !== "close" && method !== "abort") throw new Error(`Unknown WritableStream method: ${method}`);
2831
2876
  if (method === "close" || method === "abort") state.closed = true;
2832
2877
  return new PromiseStubHook((method === "write" ? args.deliverStreamWrite(state.writer) : args.deliverCall(state.writer[method], state.writer)).then((payload) => new PayloadStubHook(payload)));
2833
2878
  } catch (err) {
2879
+ args.dispose();
2834
2880
  return new ErrorStubHook(err);
2835
2881
  }
2836
2882
  }