@agoric/network 0.1.1-dev-50c9518.0 → 0.1.1-dev-d15cb41.0

package/README.md

@@ -57,15 +57,12 @@ E(home.ibcport[0]).connect(remoteEndpoint, connectionHandler)
 
 The other side of `connect()` is a "listening port". These ports are waiting for inbound connections to be established.
 
-To get a listening port, you need a `NetworkInterface` object (such as the one on your `ag-solo` under `home.network`) and ask it to `bindPort()` to an endpoint. You can either provide a specific port name, or allow the API to allocate a random one for you. The endpoint specifies the type of connection that this port will be able to accept (IBC, TCP, etc), and some properties of that connection. `bindPort()` uses a "multiaddress" to encode this information.
+To get a listening port, you need a `NetworkInterface` object (such as the one on your `ag-solo` under `home.network`) and ask it for a port, via the `PortAllocator`.
 
 ```js
 // ask for a random allocation - ends with a slash
-E(home.network).bindPort('/ibc-port/')
-  .then(port => usePort(port));
-
-// or ask for a specific port name
-E(home.network).bindPort('/ibc-port/my-cool-port-name')
+E(home.network).getPortAllocator()
+  .then(portAllocator => E(portAllocator).allocateCustomIBCPort())
   .then(port => usePort(port));
 ```
 
@@ -147,7 +144,7 @@ Note that if you want to listen on this port again, you can just call `port.addL
 
 ### Closing the Port Entirely
 
-Removing a listener doesn't release the port address to make it available for other `bindPort()` requests.  You can call:
+Removing a listener doesn't release the port address to make it available for other `PortAllocator` requests.  You can call:
 
 ```js
 port.revoke();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/network",
-  "version": "0.1.1-dev-50c9518.0+50c9518",
+  "version": "0.1.1-dev-d15cb41.0+d15cb41",
   "description": "Agoric's network protocol API",
   "type": "module",
   "main": "./src/index.js",
@@ -21,19 +21,19 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-50c9518.0+50c9518",
-    "@agoric/internal": "0.3.3-dev-50c9518.0+50c9518",
-    "@agoric/store": "0.9.3-dev-50c9518.0+50c9518",
-    "@agoric/vat-data": "0.5.3-dev-50c9518.0+50c9518",
+    "@agoric/assert": "0.6.1-dev-d15cb41.0+d15cb41",
+    "@agoric/internal": "0.3.3-dev-d15cb41.0+d15cb41",
+    "@agoric/store": "0.9.3-dev-d15cb41.0+d15cb41",
+    "@agoric/vat-data": "0.5.3-dev-d15cb41.0+d15cb41",
     "@endo/base64": "^1.0.4",
     "@endo/far": "^1.1.1",
     "@endo/patterns": "^1.3.1",
     "@endo/promise-kit": "^1.1.1"
   },
   "devDependencies": {
-    "@agoric/swingset-liveslots": "0.10.3-dev-50c9518.0+50c9518",
-    "@agoric/swingset-vat": "0.32.3-dev-50c9518.0+50c9518",
-    "@agoric/zone": "0.2.3-dev-50c9518.0+50c9518",
+    "@agoric/swingset-liveslots": "0.10.3-dev-d15cb41.0+d15cb41",
+    "@agoric/swingset-vat": "0.32.3-dev-d15cb41.0+d15cb41",
+    "@agoric/zone": "0.2.3-dev-d15cb41.0+d15cb41",
     "@endo/bundle-source": "^3.2.2",
     "ava": "^5.3.0",
     "c8": "^9.1.0"
@@ -70,5 +70,5 @@
   "typeCoverage": {
     "atLeast": 89.73
   },
-  "gitHead": "50c9518a689ad12d2ae331e158cf148b02bfdcb6"
+  "gitHead": "d15cb41b5dc7d3c47a1bc4c034ae74adfc7f838a"
 }

package/src/network.d.ts

@@ -89,6 +89,19 @@ export function prepareEchoConnectionKit(zone: import("@agoric/base-zone").Zone)
         onListen(port: any, _listenHandler: any): Promise<void>;
     };
 }>;
+export function preparePortAllocator(zone: import("@agoric/base-zone").Zone, { watch }: ReturnType<(zone: import("@agoric/base-zone").Zone, powers?: {
+    isRetryableReason?: ((reason: any) => boolean) | undefined;
+    watchPromise?: ((p: PromiseLike<any>, watcher: import("@agoric/vow/src/watch-promise.js").PromiseWatcher, ...args: unknown[]) => void) | undefined;
+} | undefined) => {
+    when: <T, TResult1 = import("@agoric/vow").Unwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("@agoric/vow/src/types.js").Unwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+    watch: <T_1 = unknown, TResult1_1 = T_1, TResult2_1 = T_1, C = unknown>(specimenP: import("@agoric/vow/src/types.js").ERef<T_1 | import("@agoric/vow/src/types.js").Vow<T_1>>, watcher?: import("@agoric/vow").Watcher<T_1, TResult1_1, TResult2_1, any> | undefined, watcherContext?: C | undefined) => import("@agoric/vow").Vow<TResult1_1 | TResult2_1>;
+    makeVowKit: <T_2>() => import("@agoric/vow").VowKit<T_2>;
+    allVows: (vows: any) => import("@agoric/vow").Vow<any>;
+}>): (args_0?: any) => import("@endo/exo").Guarded<{
+    allocateCustomIBCPort(specifiedName?: string): import("@agoric/vow").Vow<any>;
+    allocateICAControllerPort(): import("@agoric/vow").Vow<any>;
+    allocateCustomLocalPort(specifiedName?: string): import("@agoric/vow").Vow<any>;
+}>;
 export type ConnectionOpts = {
     addrs: Endpoint[];
     handlers: import("@agoric/vow").Remote<Required<ConnectionHandler>>[];

package/src/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["network.js"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,kCAFW,MAAM,YAahB;AAwsCD;;;;;GAKG;AACH,qDAHW,OAAO,mBAAmB,EAAE,IAAI,sBAChC,UAAU,QAlvCX,OAAO,mBACjB,EAAE,IAAI;;wBAIL,gBAED,WAAU,OAAQ,kCAAoB,EAGtC,cADc,WAAW,SACnB;;uFAHY,CAAC,yBAGnB,OAAO,0BAAY,EAAE,MAAM,CAAC,CAAC,CAAC;uFAkJc,OAAO,0BAAY,EAC9D,IAAI,CAAC,GAAC,GAAG,OAAO,0BAAY,EAAE,GAAG,CAAC,GAAC,CAAC,CAAC;;;EAqlCsB;;;;IAmCpD;;;;;OAKG;qCAHQ,QAAQ,cACR,QAAQ;;;IAgEnB;;;;;OAKG;kDAHQ,QAAQ;;GAiD1B;AAx4CD;;;GAGG;AACH,qCAAsC;AAG/B,0CADK,OAAO,aAWlB;AA2IM,0CARI,OAAO,cAAc,EAAE,IAAI,YAC3B,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,SACzD,QAAQ,YACR,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,SACzD,QAAQ,kBACR,CAAC,IAAI,EAAE,cAAc,KAAK,UAAU,yEAgD9C;AA66BM,6CAHI,OAAO,mBAAmB,EAAE,IAAI,UAChC,UAAU,oCAtnCnB,IAAI;;8FASN,cADc;;oJACO,MAAM;0HAmJ1B,IAAI,0CAA0B,GAAG;;;EA09B0B,iDAO7C,QAAQ,CA2BtB;AAOM,+CAFI,OAAO,mBAAmB,EAAE,IAAI;;QAsCnC;;;;WAIG;+BAHQ,UAAU,SACV,KAAK,sBACL,iBAAiB;QAU5B;;;;WAIG;6BAHQ,UAAU,YACV,WAAW;;;;YAftB;;;;eAIG;mCAHQ,UAAU,SACV,KAAK,sBACL,iBAAiB;YAU5B;;;;eAIG;iCAHQ,UAAU,YACV,WAAW;;;;GAyB7B;;WAlsCa,QAAQ,EAAE;cACV,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,EAAE;WAC3D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;aAC5B,YAAY,CAAC,QAAQ,CAAC;OACtB,CAAC,GAAC,CAAC;OACH,CAAC,GAAC,CAAC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["network.js"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,kCAFW,MAAM,YAahB;AAstCD;;;;;GAKG;AACH,qDAHW,OAAO,mBAAmB,EAAE,IAAI,sBAChC,UAAU,QAhwCX,OAAO,mBACjB,EAAE,IAAI;;wBAIL,gBAED,WAAU,OAAQ,kCAAoB,EAGtC,cADc,WAAW,SACnB;;uFAHY,CAAC,yBAGnB,OAAO,0BAAY,EAAE,MAAM,CAAC,CAAC,CAAC;uFA8IxB,OAAM,0BACJ,EAAE,IACT,CAAK,GAAH,GAAG,OAAO,0BAEZ,EAAK,GAAA,CAAC,GAAC,CACR,CAAC;;;EAmmC2D;;;;IAmCpD;;;;;OAKG;qCAHQ,QAAQ,cACR,QAAQ;;;IAgEnB;;;;;OAKG;kDAHQ,QAAQ;;GAiD1B;AAt5CD;;;GAGG;AACH,qCAAsC;AAG/B,0CADK,OAAO,aAWlB;AAyJM,0CARI,OAAO,cAAc,EAAE,IAAI,YAC3B,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,SACzD,QAAQ,YACR,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,SACzD,QAAQ,kBACR,CAAC,IAAI,EAAE,cAAc,KAAK,UAAU,yEAgD9C;AA66BM,6CAHI,OAAO,mBAAmB,EAAE,IAAI,UAChC,UAAU,oCApoCnB,IAAI;;8FASN,cADc;;oJACO,MAAM;0HA+IjB,IACT,0CAEK,GAAA;;;EAy+BsD,iDAO7C,QAAQ,CA2BtB;AAOM,+CAFI,OAAO,mBAAmB,EAAE,IAAI;;QAsCnC;;;;WAIG;+BAHQ,UAAU,SACV,KAAK,sBACL,iBAAiB;QAU5B;;;;WAIG;6BAHQ,UAAU,YACV,WAAW;;;;YAftB;;;;eAIG;mCAHQ,UAAU,SACV,KAAK,sBACL,iBAAiB;YAU5B;;;;eAIG;iCAHQ,UAAU,YACV,WAAW;;;;GAyB7B;AAsKM,2CAHI,OAAO,mBAAmB,EAAE,IAAI,aAChC,UAAU,oCA75CnB,IAAI;;8FASN,cADc;;oJACO,MAAM;0HA+IjB,IACT,0CAEK,GAAA;;;EAkwCsD;;;;GAqDzD;;WA35CW,QAAQ,EAAE;cACV,OAAO,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,EAAE;WAC3D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;aAC5B,YAAY,CAAC,QAAQ,CAAC;OACtB,CAAC,GAAC,CAAC;OACH,CAAC,GAAC,CAAC"}

package/src/network.js

@@ -46,6 +46,20 @@ export function getPrefixes(addr) {
   return ret;
 }
 
+/**
+ * Validate IBC port name
+ * @param {string} specifiedName
+ */
+function throwIfInvalidPortName(specifiedName) {
+  // Contains between 2 and 128 characters
+  // Can contain alphanumeric characters
+  // Valid symbols: ., ,, _, +, -, #, [, ], <, >
+  const portNameRegex = new RegExp('^[a-zA-Z0-9.,_+\\-#<>\\[\\]]{2,128}$');
+  if (!portNameRegex.test(specifiedName)) {
+    throw new Error(`Invalid IBC port name: ${specifiedName}`);
+  }
+}
+
 /**
  * @typedef {object} ConnectionOpts
  * @property {Endpoint[]} addrs
@@ -1426,3 +1440,61 @@ export function prepareLoopbackProtocolHandler(zone, { watch, allVows }) {
 
   return makeLoopbackProtocolHandler;
 }
+
+/**
+ *
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {ReturnType<import('@agoric/vow').prepareVowTools>} powers
+ */
+export const preparePortAllocator = (zone, { watch }) =>
+  zone.exoClass(
+    'PortAllocator',
+    M.interface('PortAllocator', {
+      allocateCustomIBCPort: M.callWhen()
+        .optional(M.string())
+        .returns(Shape.Vow$(Shape.Port)),
+      allocateICAControllerPort: M.callWhen().returns(Shape.Vow$(Shape.Port)),
+      allocateCustomLocalPort: M.callWhen()
+        .optional(M.string())
+        .returns(Shape.Vow$(Shape.Port)),
+    }),
+    ({ protocol }) => ({ protocol, lastICAPortNum: 0n }),
+    {
+      allocateCustomIBCPort(specifiedName = '') {
+        const { state } = this;
+        let localAddr = `/ibc-port/`;
+
+        if (specifiedName) {
+          throwIfInvalidPortName(specifiedName);
+
+          localAddr = `/ibc-port/custom-${specifiedName}`;
+        }
+
+        // Allocate an IBC port with a unique generated name.
+        return watch(E(state.protocol).bindPort(localAddr));
+      },
+      allocateICAControllerPort() {
+        const { state } = this;
+        state.lastICAPortNum += 1n;
+        return watch(
+          E(state.protocol).bindPort(
+            `/ibc-port/icacontroller-${state.lastICAPortNum}`,
+          ),
+        );
+      },
+      allocateCustomLocalPort(specifiedName = '') {
+        const { state } = this;
+
+        let localAddr = `/local/`;
+
+        if (specifiedName) {
+          throwIfInvalidPortName(specifiedName);
+
+          localAddr = `/local/custom-${specifiedName}`;
+        }
+
+        // Allocate a local port with a unique generated name.
+        return watch(E(state.protocol).bindPort(localAddr));
+      },
+    },
+  );

package/src/types.d.ts

@@ -210,6 +210,7 @@ type ProtocolImpl = {
      */
     outbound: (port: Remote<Port>, remoteAddr: Endpoint, connectionHandler: Remote<ConnectionHandler>) => PromiseVow<Connection>;
 };
+type PortAllocator = ReturnType<ReturnType<typeof import("@agoric/network").preparePortAllocator>>;
 import type { PromiseVow } from '@agoric/vow';
 import type { Remote } from '@agoric/vow';
 //# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":";;;qBAO8D,CAAC,sCAAqB,CAAC,mBAD7D,GAAG,EAAE,KAAK,GAAG,IACyB,CAAC,AAAjD,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,OAAO,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;;;;aAK5E,MAAM;;;;;gBAIN,MAAM;;;;;;;;;;;;;;;;;;uBAWI,QAAQ;;;;;;;;;;qBAMjB,MAAM,QAAQ;;;;;;;;sBAKf,QAAQ;;;;;;;;;;;;;;;;;;;;;;8CAeL,QAAQ,cACP,QAAQ;;;;gDAMT,QAAQ,cACP,QAAQ;;;;yCAIe,GAAG;;;;;;;;;;;wBASzB,KAAK,SACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;;;;;;qBAIjB,MAAM,QAAQ;;;;sBAEd,MAAM,QAAQ;;;;;;;;;0DAOZ,QAAQ,cACP,QAAQ;;;;uDAMf,KAAK,uCAEH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;yDAKjB,WAAW;;;;;mBAKZ,GAAG,GAAG,IAAI;;;;;;;;;;;;;;;;;;gCAeG,QAAQ;;;;4CAIlB,QAAQ;;;;8CAMR,QAAQ;;;;oDAOR,QAAQ;;;;qDAOR,QAAQ,UACX,QAAQ;;;;+CAML,QAAQ,UACX,QAAQ;;;;8CAOL,QAAQ;;;;;;;;;mBAMH,kBAAkB;;;;;qBAEzB,MAAM,QAAQ;;;;;sBAEd,MAAM,QAAQ;;;;;;;;;;;;;;uBAKL,QAAQ;;;;0BAGd,QAAQ,cACR,QAAQ;;;;+CAKR,QAAQ;;gCAvLa,aAAa;4BAAb,aAAa"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":";;;qBAO8D,CAAC,sCAAqB,CAAC,mBAD7D,GAAG,EAAE,KAAK,GAAG,IACyB,CAAC,AAAjD,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,OAAO,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;;;;aAK5E,MAAM;;;;;gBAIN,MAAM;;;;;;;;;;;;;;;;;;uBAWI,QAAQ;;;;;;;;;;qBAMjB,MAAM,QAAQ;;;;;;;;sBAKf,QAAQ;;;;;;;;;;;;;;;;;;;;;;8CAeL,QAAQ,cACP,QAAQ;;;;gDAMT,QAAQ,cACP,QAAQ;;;;yCAIe,GAAG;;;;;;;;;;;wBASzB,KAAK,SACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;;;;;;qBAIjB,MAAM,QAAQ;;;;sBAEd,MAAM,QAAQ;;;;;;;;;0DAOZ,QAAQ,cACP,QAAQ;;;;uDAMf,KAAK,uCAEH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;yDAKjB,WAAW;;;;;mBAKZ,GAAG,GAAG,IAAI;;;;;;;;;;;;;;;;;;gCAeG,QAAQ;;;;4CAIlB,QAAQ;;;;8CAMR,QAAQ;;;;oDAOR,QAAQ;;;;qDAOR,QAAQ,UACX,QAAQ;;;;+CAML,QAAQ,UACX,QAAQ;;;;8CAOL,QAAQ;;;;;;;;;mBAMH,kBAAkB;;;;;qBAEzB,MAAM,QAAQ;;;;;sBAEd,MAAM,QAAQ;;;;;;;;;;;;;;uBAKL,QAAQ;;;;0BAGd,QAAQ,cACR,QAAQ;;;;+CAKR,QAAQ;;qBAMX,UAAU,CAAC,UAAU,CAAC,cAAc,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;gCA7LrD,aAAa;4BAAb,aAAa"}

package/src/types.js

@@ -188,3 +188,5 @@
  * ) => PromiseVow<Connection>} outbound
  *   Create an outbound connection
  */
+
+/** @typedef {ReturnType<ReturnType<typeof import('@agoric/network').preparePortAllocator>>} PortAllocator */