@agoric/network 0.1.1-calypso-dev-84eb287.0

package/src/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Rearrange the exo types to make a cast of the methods (M) and init function (I) to a specific type.
+ */
+export type ExoClassMethods<M extends import("@endo/exo").Methods, I extends (...args: any[]) => any> = M & ThisType<{
+    self: import("@endo/exo").Guarded<M>;
+    state: ReturnType<I>;
+}>;
+/**
+ * Each character code carries 8-bit octets.  Eventually we want to use passable Uint8Arrays.
+ */
+export type Bytes = string;
+/**
+ * A local or remote address See multiaddr.js for an
+ *   opinionated router implementation
+ */
+export type Endpoint = string;
+/**
+ * A closable object
+ */
+export type ClosableI = {
+    /**
+     * Terminate the object
+     */
+    close: () => PromiseVow<void>;
+};
+export type Closable = RemotableObject & ClosableI;
+/**
+ * The network Protocol
+ */
+export type Protocol = {
+    /**
+     * Claim a port, or if
+     * ending in ENDPOINT_SEPARATOR, a fresh name
+     */
+    bindPort: (prefix: Endpoint) => PromiseVow<Port>;
+};
+/**
+ * A port that has been bound to a protocol
+ */
+export type Port = {
+    /**
+     * Get the locally bound name of this
+     * port
+     */
+    getLocalAddress: () => Endpoint;
+    /**
+     *   Begin accepting incoming connections
+     */
+    addListener: (acceptHandler: Remote<ListenHandler>) => PromiseVow<void>;
+    /**
+     *   Make an outbound connection
+     */
+    connect: (remote: Endpoint, connectionHandler?: Remote<ConnectionHandler>) => PromiseVow<Connection>;
+    /**
+     *   Remove the currently-bound listener
+     */
+    removeListener: (acceptHandler: Remote<ListenHandler>) => PromiseVow<void>;
+    /**
+     * Deallocate the port entirely, removing all
+     * listeners and closing all active connections
+     */
+    revoke: () => PromiseVow<void>;
+};
+/**
+ * A handler for incoming connections
+ */
+export type ListenHandler = {
+    /**
+     * The listener has been registered
+     */
+    onListen?: ((port: Remote<Port>, l: Remote<ListenHandler>) => PromiseVow<void>) | undefined;
+    /**
+     *   A new connection is incoming
+     */
+    onAccept: (port: Remote<Port>, localAddr: Endpoint, remoteAddr: Endpoint, l: Remote<ListenHandler>) => PromiseVow<Remote<ConnectionHandler>>;
+    /**
+     * The connection was rejected
+     */
+    onReject?: ((port: Remote<Port>, localAddr: Endpoint, remoteAddr: Endpoint, l: Remote<ListenHandler>) => PromiseVow<void>) | undefined;
+    /**
+     * There was an error while listening
+     */
+    onError?: ((port: Remote<Port>, rej: any, l: Remote<ListenHandler>) => PromiseVow<void>) | undefined;
+    /**
+     * The
+     * listener has been removed
+     */
+    onRemove?: ((port: Remote<Port>, l: Remote<ListenHandler>) => PromiseVow<void>) | undefined;
+};
+export type ConnectionI = {
+    /**
+     *   Send a packet on the connection
+     */
+    send: (packetBytes: Bytes, opts?: Record<string, any>) => PromiseVow<Bytes>;
+    /**
+     * Close both ends of the connection
+     */
+    close: () => PromiseVow<void>;
+    /**
+     * Get the locally bound name of this
+     * connection
+     */
+    getLocalAddress: () => Endpoint;
+    /**
+     * Get the name of the counterparty
+     */
+    getRemoteAddress: () => Endpoint;
+};
+export type Connection = RemotableObject & ConnectionI;
+/**
+ * A handler for a given Connection
+ */
+export type ConnectionHandler = {
+    /**
+     * The connection has been opened
+     */
+    onOpen?: ((connection: Remote<Connection>, localAddr: Endpoint, remoteAddr: Endpoint, c: Remote<ConnectionHandler>) => PromiseVow<void>) | undefined;
+    /**
+     * The connection received a packet
+     */
+    onReceive?: ((connection: Remote<Connection>, ack: Bytes, c: Remote<ConnectionHandler>, opts?: Record<string, any>) => PromiseVow<Bytes>) | undefined;
+    /**
+     * The connection has been closed
+     */
+    onClose?: ((connection: Remote<Connection>, reason?: CloseReason, c?: Remote<ConnectionHandler>) => PromiseVow<void>) | undefined;
+};
+/**
+ * The reason a connection was closed
+ */
+export type CloseReason = any | null;
+export type AttemptDescription = {
+    handler: Remote<ConnectionHandler>;
+    remoteAddress?: string | undefined;
+    localAddress?: string | undefined;
+};
+/**
+ * A handler for things the protocol
+ *   implementation will invoke
+ */
+export type ProtocolHandler = {
+    /**
+     *   This protocol is created
+     */
+    onCreate: (protocol: Remote<ProtocolImpl>, p: Remote<ProtocolHandler>) => PromiseVow<void>;
+    /**
+     *   Create a fresh port identifier for this protocol
+     */
+    generatePortID: (localAddr: Endpoint, p: Remote<ProtocolHandler>) => PromiseVow<string>;
+    /**
+     *   A port will be bound
+     */
+    onBind: (port: Remote<Port>, localAddr: Endpoint, p: Remote<ProtocolHandler>) => PromiseVow<void>;
+    /**
+     *   A port was listening
+     */
+    onListen: (port: Remote<Port>, localAddr: Endpoint, listenHandler: Remote<ListenHandler>, p: Remote<ProtocolHandler>) => PromiseVow<void>;
+    /**
+     *   A port listener has been reset
+     */
+    onListenRemove: (port: Remote<Port>, localAddr: Endpoint, listenHandler: Remote<ListenHandler>, p: Remote<ProtocolHandler>) => PromiseVow<void>;
+    /**
+     * Return unique suffix for local address
+     */
+    onInstantiate?: ((port: Remote<Port>, localAddr: Endpoint, remote: Endpoint, p: Remote<ProtocolHandler>) => PromiseVow<Endpoint>) | undefined;
+    /**
+     *   A port initiates an outbound connection
+     */
+    onConnect: (port: Remote<Port>, localAddr: Endpoint, remote: Endpoint, c: Remote<ConnectionHandler>, p: Remote<ProtocolHandler>) => PromiseVow<AttemptDescription>;
+    /**
+     *   The port is being completely destroyed
+     */
+    onRevoke: (port: Remote<Port>, localAddr: Endpoint, p: Remote<ProtocolHandler>) => PromiseVow<void>;
+};
+/**
+ * An inbound connection attempt
+ */
+export type InboundAttempt = {
+    /**
+     *   Establish the connection
+     */
+    accept: (desc: AttemptDescription) => PromiseVow<Connection>;
+    /**
+     * Return the local address for this
+     * attempt
+     */
+    getLocalAddress: () => Endpoint;
+    /**
+     * Return the remote address for
+     * this attempt
+     */
+    getRemoteAddress: () => Endpoint;
+    /**
+     * Abort the attempt
+     */
+    close: () => PromiseVow<void>;
+};
+/**
+ * Things the protocol can do for us
+ */
+export type ProtocolImpl = {
+    /**
+     * Claim a port, or if
+     * ending in ENDPOINT_SEPARATOR, a fresh name
+     */
+    bindPort: (prefix: Endpoint) => PromiseVow<Remote<Port>>;
+    /**
+     *   Make an attempt to connect into this protocol
+     */
+    inbound: (listenAddr: Endpoint, remoteAddr: Endpoint) => PromiseVow<InboundAttempt>;
+    /**
+     *   Create an outbound connection
+     */
+    outbound: (port: Remote<Port>, remoteAddr: Endpoint, connectionHandler: Remote<ConnectionHandler>) => PromiseVow<Connection>;
+};
+import type { PromiseVow } from '@agoric/vow';
+import type { RemotableObject } from '@endo/pass-style';
+import type { Remote } from '@agoric/vow';
+//# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"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"}

package/src/types.js

@@ -0,0 +1,202 @@
+// @ts-check
+
+// Ensure this is a module.
+export {};
+
+/**
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {PromiseVow, Remote} from '@agoric/vow';
+ */
+
+/**
+ * @template {import('@endo/exo').Methods} M
+ * @template {(...args: any[]) => any} I
+ * @typedef {M & ThisType<{ self: import('@endo/exo').Guarded<M>, state: ReturnType<I> }>} ExoClassMethods
+ * Rearrange the exo types to make a cast of the methods (M) and init function (I) to a specific type.
+ */
+
+/**
+ * @typedef {string} Bytes Each character code carries 8-bit octets.  Eventually we want to use passable Uint8Arrays.
+ */
+
+/**
+ * @typedef {string} Endpoint A local or remote address See multiaddr.js for an
+ *   opinionated router implementation
+ */
+
+/**
+ * @typedef {object} ClosableI A closable object
+ * @property {() => PromiseVow<void>} close Terminate the object
+ */
+/**
+ * @typedef {RemotableObject & ClosableI} Closable
+ */
+
+/**
+ * @typedef {object} Protocol The network Protocol
+ * @property {(prefix: Endpoint) => PromiseVow<Port>} bindPort Claim a port, or if
+ *   ending in ENDPOINT_SEPARATOR, a fresh name
+ */
+
+/**
+ * @typedef {object} Port A port that has been bound to a protocol
+ * @property {() => Endpoint} getLocalAddress Get the locally bound name of this
+ *   port
+ * @property {(acceptHandler: Remote<ListenHandler>) => PromiseVow<void>} addListener
+ *   Begin accepting incoming connections
+ * @property {(
+ *   remote: Endpoint,
+ *   connectionHandler?: Remote<ConnectionHandler>,
+ * ) => PromiseVow<Connection>} connect
+ *   Make an outbound connection
+ * @property {(acceptHandler: Remote<ListenHandler>) => PromiseVow<void>} removeListener
+ *   Remove the currently-bound listener
+ * @property {() => PromiseVow<void>} revoke Deallocate the port entirely, removing all
+ *   listeners and closing all active connections
+ */
+
+/**
+ * @typedef {object} ListenHandler A handler for incoming connections
+ * @property {(port: Remote<Port>, l: Remote<ListenHandler>) => PromiseVow<void>} [onListen] The listener has been registered
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   remoteAddr: Endpoint,
+ *   l: Remote<ListenHandler>,
+ * ) => PromiseVow<Remote<ConnectionHandler>>} onAccept
+ *   A new connection is incoming
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   remoteAddr: Endpoint,
+ *   l: Remote<ListenHandler>,
+ * ) => PromiseVow<void>} [onReject]
+ *   The connection was rejected
+ * @property {(port: Remote<Port>, rej: any, l: Remote<ListenHandler>) => PromiseVow<void>} [onError]
+ *   There was an error while listening
+ * @property {(port: Remote<Port>, l: Remote<ListenHandler>) => PromiseVow<void>} [onRemove] The
+ *   listener has been removed
+ */
+
+/**
+ * @typedef {object} ConnectionI
+ * @property {(
+ *   packetBytes: Bytes,
+ *   opts?: Record<string, any>,
+ * ) => PromiseVow<Bytes>} send
+ *   Send a packet on the connection
+ * @property {() => PromiseVow<void>} close Close both ends of the connection
+ * @property {() => Endpoint} getLocalAddress Get the locally bound name of this
+ *   connection
+ * @property {() => Endpoint} getRemoteAddress Get the name of the counterparty
+ */
+/**
+ * @typedef {RemotableObject & ConnectionI} Connection
+ */
+
+/**
+ * @typedef {object} ConnectionHandler A handler for a given Connection
+ * @property {(
+ *   connection: Remote<Connection>,
+ *   localAddr: Endpoint,
+ *   remoteAddr: Endpoint,
+ *   c: Remote<ConnectionHandler>,
+ * ) => PromiseVow<void>} [onOpen]
+ *   The connection has been opened
+ * @property {(
+ *   connection: Remote<Connection>,
+ *   ack: Bytes,
+ *   c: Remote<ConnectionHandler>,
+ *   opts?: Record<string, any>,
+ * ) => PromiseVow<Bytes>} [onReceive]
+ *   The connection received a packet
+ * @property {(
+ *   connection: Remote<Connection>,
+ *   reason?: CloseReason,
+ *   c?: Remote<ConnectionHandler>,
+ * ) => PromiseVow<void>} [onClose]
+ *   The connection has been closed
+ *
+ * @typedef {any | null} CloseReason The reason a connection was closed
+ */
+
+/**
+ * @typedef {object} AttemptDescription
+ * @property {Remote<ConnectionHandler>} handler
+ * @property {Endpoint} [remoteAddress]
+ * @property {Endpoint} [localAddress]
+ */
+
+/**
+ * @typedef {object} ProtocolHandler A handler for things the protocol
+ *   implementation will invoke
+ * @property {(protocol: Remote<ProtocolImpl>, p: Remote<ProtocolHandler>) => PromiseVow<void>} onCreate
+ *   This protocol is created
+ * @property {(localAddr: Endpoint, p: Remote<ProtocolHandler>) => PromiseVow<string>} generatePortID
+ *   Create a fresh port identifier for this protocol
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<void>} onBind
+ *   A port will be bound
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   listenHandler: Remote<ListenHandler>,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<void>} onListen
+ *   A port was listening
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   listenHandler: Remote<ListenHandler>,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<void>} onListenRemove
+ *   A port listener has been reset
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   remote: Endpoint,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<Endpoint>} [onInstantiate]
+ *   Return unique suffix for local address
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   remote: Endpoint,
+ *   c: Remote<ConnectionHandler>,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<AttemptDescription>} onConnect
+ *   A port initiates an outbound connection
+ * @property {(
+ *   port: Remote<Port>,
+ *   localAddr: Endpoint,
+ *   p: Remote<ProtocolHandler>,
+ * ) => PromiseVow<void>} onRevoke
+ *   The port is being completely destroyed
+ *
+ * @typedef {object} InboundAttempt An inbound connection attempt
+ * @property {(desc: AttemptDescription) => PromiseVow<Connection>} accept
+ *   Establish the connection
+ * @property {() => Endpoint} getLocalAddress Return the local address for this
+ *   attempt
+ * @property {() => Endpoint} getRemoteAddress Return the remote address for
+ *   this attempt
+ * @property {() => PromiseVow<void>} close Abort the attempt
+ *
+ * @typedef {object} ProtocolImpl Things the protocol can do for us
+ * @property {(prefix: Endpoint) => PromiseVow<Remote<Port>>} bindPort Claim a port, or if
+ *   ending in ENDPOINT_SEPARATOR, a fresh name
+ * @property {(
+ *   listenAddr: Endpoint,
+ *   remoteAddr: Endpoint,
+ * ) => PromiseVow<InboundAttempt>} inbound
+ *   Make an attempt to connect into this protocol
+ * @property {(
+ *   port: Remote<Port>,
+ *   remoteAddr: Endpoint,
+ *   connectionHandler: Remote<ConnectionHandler>,
+ * ) => PromiseVow<Connection>} outbound
+ *   Create an outbound connection
+ */