starpc 0.1.7 → 0.2.0

package/dist/srpc/client.js

@@ -1,27 +1,8 @@
-import { from as observableFrom } from 'rxjs';
-import { ClientRPC } from './client-rpc';
 import { pipe } from 'it-pipe';
 import { pushable } from 'it-pushable';
-import { decodePacketSource, encodePacketSource, parseLengthPrefixTransform, prependLengthPrefixTransform, } from './packet';
-// unaryDataCb builds a new unary request data callback.
-function unaryDataCb(resolve) {
-    return async (data) => {
-        // resolve the promise
-        resolve(data);
-        // this is the last data we expect.
-        return false;
-    };
-}
-// streamingDataCb builds a new streaming request data callback.
-/*
-function streamingDataCb(resolve: (data: Uint8Array) => void): DataCb {
-  return async (
-    data: Uint8Array
-  ): Promise<boolean | void> => {
-    // TODO
-  }
-}
-*/
+import { from as observableFrom } from 'rxjs';
+import { ClientRPC } from './client-rpc.js';
+import { decodePacketSource, encodePacketSource, parseLengthPrefixTransform, prependLengthPrefixTransform, } from './packet.js';
 // writeClientStream registers the subscriber to write the client data stream.
 function writeClientStream(call, data) {
     data.subscribe({
@@ -32,20 +13,10 @@ function writeClientStream(call, data) {
             call.close(err);
         },
         complete() {
-            call.writeCallData(new Uint8Array(0), true);
+            call.writeCallData(undefined, true);
         },
     });
 }
-// waitCallComplete handles the call complete promise.
-function waitCallComplete(call, resolve, reject) {
-    call
-        .waitComplete()
-        .catch(reject)
-        .finally(() => {
-        // ensure we resolve it if no data was ever returned.
-        resolve(new Uint8Array());
-    });
-}
 // Client implements the ts-proto Rpc interface with the drpcproto protocol.
 export class Client {
     // openConnFn is the open connection function.
@@ -56,47 +27,42 @@ export class Client {
     }
     // request starts a non-streaming request.
     async request(service, method, data) {
-        return new Promise((resolve, reject) => {
-            const dataCb = unaryDataCb(resolve);
-            this.startRpc(service, method, data, dataCb)
-                .then((call) => {
-                waitCallComplete(call, resolve, reject);
-            })
-                .catch(reject);
-        });
+        const call = await this.startRpc(service, method, data);
+        for await (const data of call.rpcDataSource) {
+            call.close();
+            return data;
+        }
+        const err = new Error('empty response');
+        call.close(err);
+        throw err;
     }
     // clientStreamingRequest starts a client side streaming request.
-    clientStreamingRequest(service, method, data) {
-        return new Promise((resolve, reject) => {
-            const dataCb = unaryDataCb(resolve);
-            this.startRpc(service, method, null, dataCb)
-                .then((call) => {
-                writeClientStream(call, data);
-                waitCallComplete(call, resolve, reject);
-            })
-                .catch(reject);
-        });
+    async clientStreamingRequest(service, method, data) {
+        const call = await this.startRpc(service, method, null);
+        writeClientStream(call, data);
+        for await (const data of call.rpcDataSource) {
+            call.close();
+            return data;
+        }
+        const err = new Error('empty response');
+        call.close(err);
+        throw err;
     }
     // serverStreamingRequest starts a server-side streaming request.
     serverStreamingRequest(service, method, data) {
         const pushServerData = pushable();
         const serverData = observableFrom(pushServerData);
-        const dataCb = async (data) => {
-            // push the message to the observable
-            pushServerData.push(data);
-            // expect more messages
-            return true;
-        };
-        this.startRpc(service, method, data, dataCb)
-            .then((call) => {
-            call
-                .waitComplete()
-                .catch((err) => {
+        this.startRpc(service, method, data)
+            .then(async (call) => {
+            try {
+                for await (const data of call.rpcDataSource) {
+                    pushServerData.push(data);
+                }
+            }
+            catch (err) {
                 pushServerData.throw(err);
-            })
-                .finally(() => {
-                pushServerData.end();
-            });
+            }
+            pushServerData.end();
         })
             .catch(pushServerData.throw.bind(pushServerData));
         return serverData;
@@ -105,32 +71,38 @@ export class Client {
     bidirectionalStreamingRequest(service, method, data) {
         const pushServerData = pushable();
         const serverData = observableFrom(pushServerData);
-        const dataCb = async (data) => {
-            // push the message to the observable
-            pushServerData.push(data);
-            // expect more messages
-            return true;
-        };
-        this.startRpc(service, method, null, dataCb)
-            .then((call) => {
-            writeClientStream(call, data);
-            call
-                .waitComplete()
-                .catch((err) => {
+        this.startRpc(service, method, null)
+            .then(async (call) => {
+            try {
+                data.subscribe({
+                    next(value) {
+                        call.writeCallData(value);
+                    },
+                    error(err) {
+                        call.close(err);
+                    },
+                    complete() {
+                        call.close();
+                    },
+                });
+                for await (const data of call.rpcDataSource) {
+                    pushServerData.push(data);
+                }
+            }
+            catch (err) {
                 pushServerData.throw(err);
-            })
-                .finally(() => {
-                pushServerData.end();
-            });
+            }
+            pushServerData.end();
         })
             .catch(pushServerData.throw.bind(pushServerData));
         return serverData;
     }
     // startRpc is a common utility function to begin a rpc call.
     // throws any error starting the rpc call
-    async startRpc(rpcService, rpcMethod, data, dataCb) {
+    // if data == null and data.length == 0, sends a separate data packet.
+    async startRpc(rpcService, rpcMethod, data) {
         const conn = await this.openConnFn();
-        const call = new ClientRPC(rpcService, rpcMethod, dataCb);
+        const call = new ClientRPC(rpcService, rpcMethod);
         pipe(conn, parseLengthPrefixTransform(), decodePacketSource, call, encodePacketSource, prependLengthPrefixTransform(), conn);
         await call.writeCallStart(data || undefined);
         return call;

package/dist/srpc/common-rpc.d.ts

@@ -0,0 +1,24 @@
+import type { Source, Sink } from 'it-stream-types';
+import type { CallData, CallStart } from './rpcproto.js';
+import { Packet } from './rpcproto.js';
+export declare class CommonRPC {
+    sink: Sink<Packet>;
+    source: AsyncIterable<Packet>;
+    private readonly _source;
+    readonly rpcDataSource: Source<Uint8Array>;
+    private readonly _rpcDataSource;
+    protected service?: string;
+    protected method?: string;
+    constructor();
+    writeCallData(data?: Uint8Array, complete?: boolean, error?: string): Promise<void>;
+    protected writePacket(packet: Packet): Promise<void>;
+    handleMessage(message: Uint8Array): Promise<void>;
+    handlePacket(packet: Partial<Packet>): Promise<void>;
+    handleCallStart(packet: Partial<CallStart>): Promise<void>;
+    protected pushRpcData(data: Uint8Array | undefined, dataIsZero: boolean | undefined): void;
+    handleCallData(packet: Partial<CallData>): Promise<void>;
+    close(err?: Error): Promise<void>;
+    private _createSink;
+    private _createSource;
+    private _createRpcDataSource;
+}

package/dist/srpc/common-rpc.js

@@ -0,0 +1,140 @@
+import { pushable } from 'it-pushable';
+import { Packet } from './rpcproto.js';
+// CommonRPC is common logic between server and client RPCs.
+export class CommonRPC {
+    // sink is the data sink for incoming messages.
+    sink;
+    // source is the packet source for outgoing Packets.
+    source;
+    // _source is used to write to the source.
+    _source;
+    // rpcDataSource emits incoming client RPC messages to the caller.
+    rpcDataSource;
+    // _rpcDataSource is used to write to the rpc message source.
+    _rpcDataSource;
+    // service is the rpc service
+    service;
+    // method is the rpc method
+    method;
+    constructor() {
+        this.sink = this._createSink();
+        const sourcev = this._createSource();
+        this.source = sourcev;
+        this._source = sourcev;
+        const rpcDataSource = this._createRpcDataSource();
+        this.rpcDataSource = rpcDataSource;
+        this._rpcDataSource = rpcDataSource;
+    }
+    // writeCallData writes the call data packet.
+    async writeCallData(data, complete, error) {
+        const callData = {
+            data: data || new Uint8Array(0),
+            dataIsZero: !!data && data.length === 0,
+            complete: complete || false,
+            error: error || '',
+        };
+        await this.writePacket({
+            body: {
+                $case: 'callData',
+                callData,
+            },
+        });
+    }
+    // writePacket writes a packet to the stream.
+    async writePacket(packet) {
+        this._source.push(packet);
+    }
+    // handleMessage handles an incoming encoded Packet.
+    //
+    // note: closes the stream if any error is thrown.
+    async handleMessage(message) {
+        return this.handlePacket(Packet.decode(message));
+    }
+    // handlePacket handles an incoming packet.
+    //
+    // note: closes the stream if any error is thrown.
+    async handlePacket(packet) {
+        try {
+            switch (packet?.body?.$case) {
+                case 'callStart':
+                    await this.handleCallStart(packet.body.callStart);
+                    break;
+                case 'callData':
+                    await this.handleCallData(packet.body.callData);
+                    break;
+            }
+        }
+        catch (err) {
+            let asError = err;
+            if (!asError?.message) {
+                asError = new Error('error handling packet');
+            }
+            this.close(asError);
+            throw asError;
+        }
+    }
+    // handleCallStart handles a CallStart packet.
+    async handleCallStart(packet) {
+        // no-op
+        throw new Error(`unexpected call start: ${packet.rpcService}/${packet.rpcMethod}`);
+    }
+    // pushRpcData pushes incoming rpc data to the rpc data source.
+    pushRpcData(data, dataIsZero) {
+        if (dataIsZero) {
+            if (!data || data.length !== 0) {
+                data = new Uint8Array(0);
+            }
+        }
+        else if (!data || data.length === 0) {
+            return;
+        }
+        this._rpcDataSource.push(data);
+    }
+    // handleCallData handles a CallData packet.
+    async handleCallData(packet) {
+        if (!this.service || !this.method) {
+            throw new Error('call start must be sent before call data');
+        }
+        this.pushRpcData(packet.data, packet.dataIsZero);
+        if (packet.error) {
+            this._rpcDataSource.end(new Error(packet.error));
+        }
+        else if (packet.complete) {
+            this._rpcDataSource.end();
+        }
+    }
+    // close marks the call as complete, optionally with an error.
+    async close(err) {
+        this._rpcDataSource.end(err);
+        this._source.end(err);
+    }
+    // _createSink returns a value for the sink field.
+    _createSink() {
+        return async (source) => {
+            try {
+                for await (const msg of source) {
+                    await this.handlePacket(msg);
+                }
+            }
+            catch (err) {
+                const anyErr = err;
+                if (anyErr?.code !== 'ERR_MPLEX_STREAM_RESET') {
+                    this.close(err);
+                }
+            }
+            this._rpcDataSource.end();
+        };
+    }
+    // _createSource returns a value for the source field.
+    _createSource() {
+        return pushable({
+            objectMode: true,
+        });
+    }
+    // _createRpcDataSource returns a value for the rpc data source field.
+    _createRpcDataSource() {
+        return pushable({
+            objectMode: true,
+        });
+    }
+}

package/dist/srpc/conn.d.ts

@@ -1,18 +1,23 @@
 import type { Stream } from '@libp2p/interface-connection';
 import type { StreamMuxerFactory } from '@libp2p/interface-stream-muxer';
 import type { Duplex } from 'it-stream-types';
-import type { Stream as SRPCStream } from './stream';
-import { Client } from './client';
+import type { OpenStreamFunc, Stream as SRPCStream } from './stream.js';
+import { Client } from './client.js';
 export interface ConnParams {
     muxerFactory?: StreamMuxerFactory;
 }
+export interface StreamHandler {
+    handleStream(strm: Duplex<Uint8Array>): Promise<void>;
+}
 export declare class Conn implements Duplex<Uint8Array> {
     private muxer;
-    constructor(connParams?: ConnParams);
+    private server?;
+    constructor(server?: StreamHandler, connParams?: ConnParams);
     get sink(): import("it-stream-types").Sink<Uint8Array, Promise<void>>;
     get source(): import("it-stream-types").Source<Uint8Array>;
     get streams(): Stream[];
     buildClient(): Client;
     openStream(): Promise<SRPCStream>;
+    buildOpenStreamFunc(): OpenStreamFunc;
     private handleIncomingStream;
 }

package/dist/srpc/conn.js

@@ -1,10 +1,18 @@
 import { Mplex } from '@libp2p/mplex';
-import { Client } from './client';
+import { Client } from './client.js';
 // Conn implements a generic connection with a two-way stream.
+// Implements the client by opening streams with the remote.
+// Implements the server by handling incoming streams.
+// If the server is unset, rejects any incoming streams.
 export class Conn {
     // muxer is the mplex stream muxer.
     muxer;
-    constructor(connParams) {
+    // server is the server side, if set.
+    server;
+    constructor(server, connParams) {
+        if (server) {
+            this.server = server;
+        }
         let muxerFactory = connParams?.muxerFactory;
         if (!muxerFactory) {
             muxerFactory = new Mplex();
@@ -33,8 +41,16 @@ export class Conn {
     async openStream() {
         return this.muxer.newStream();
     }
+    // buildOpenStreamFunc returns openStream bound to this conn.
+    buildOpenStreamFunc() {
+        return this.openStream.bind(this);
+    }
     // handleIncomingStream handles an incoming stream.
     handleIncomingStream(strm) {
-        strm.abort(new Error('server -> client streams not implemented'));
+        const server = this.server;
+        if (!server) {
+            return strm.abort(new Error('server not implemented'));
+        }
+        server.handleStream(strm);
     }
 }

package/dist/srpc/definition.d.ts

@@ -0,0 +1,15 @@
+import { MessageDefinition } from './message';
+export interface Definition {
+    name: string;
+    fullName: string;
+    methods: {
+        [id: string]: MethodDefinition<unknown, unknown>;
+    };
+}
+export interface MethodDefinition<RequestType, ResponseType> {
+    name: string;
+    requestType: MessageDefinition<RequestType>;
+    requestStream: boolean;
+    responseType: MessageDefinition<ResponseType>;
+    responseStream: boolean;
+}

package/dist/srpc/definition.js

@@ -0,0 +1 @@
+export {};

package/dist/srpc/handler.d.ts

@@ -0,0 +1,24 @@
+import type { Sink, Source } from 'it-stream-types';
+import { Observable } from 'rxjs';
+import { Definition, MethodDefinition } from './definition.js';
+export declare type InvokeFn = (dataSource: Source<Uint8Array>, dataSink: Sink<Uint8Array>) => Promise<void>;
+export interface Handler {
+    getServiceID(): string;
+    getMethodIDs(): string[];
+    lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>;
+}
+export declare type MethodMap = {
+    [name: string]: InvokeFn;
+};
+export declare class StaticHandler implements Handler {
+    private service;
+    private methods;
+    constructor(serviceID: string, methods: MethodMap);
+    getServiceID(): string;
+    getMethodIDs(): string[];
+    lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>;
+}
+declare type MethodProto = ((request: unknown) => Promise<unknown>) | ((request: unknown) => Observable<unknown>) | ((request: Observable<unknown>) => Promise<unknown>) | ((request: Observable<unknown>) => Observable<unknown>);
+export declare function createInvokeFn(methodInfo: MethodDefinition<unknown, unknown>, methodProto: MethodProto): InvokeFn;
+export declare function createHandler(definition: Definition, impl: any): Handler;
+export {};

package/dist/srpc/handler.js

@@ -0,0 +1,123 @@
+import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
+import { from as observableFrom } from 'rxjs';
+import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
+// StaticHandler is a handler with a definition and implementation.
+export class StaticHandler {
+    // service is the service id
+    service;
+    // methods is the map of method to invoke fn
+    methods;
+    constructor(serviceID, methods) {
+        this.service = serviceID;
+        this.methods = methods;
+    }
+    // getServiceID returns the ID of the service.
+    getServiceID() {
+        return this.service;
+    }
+    // getMethodIDs returns the IDs of the methods.
+    getMethodIDs() {
+        return Object.keys(this.methods);
+    }
+    // lookupMethod looks up the method matching the service & method ID.
+    // returns null if not found.
+    async lookupMethod(serviceID, methodID) {
+        if (serviceID && serviceID !== this.service) {
+            return null;
+        }
+        return this.methods[methodID] || null;
+    }
+}
+// createInvokeFn builds an InvokeFn from a method definition and a function prototype.
+export function createInvokeFn(methodInfo, methodProto) {
+    const requestDecode = buildDecodeMessageTransform(methodInfo.requestType);
+    return async (dataSource, dataSink) => {
+        // responseSink is a Sink for response messages.
+        const responseSink = pushable({
+            objectMode: true,
+        });
+        // pipe responseSink to dataSink.
+        const responsePipe = pipe(responseSink, buildEncodeMessageTransform(methodInfo.responseType), dataSink);
+        // build the request argument.
+        let requestArg;
+        if (methodInfo.requestStream) {
+            // requestSource is a Source of decoded request messages.
+            const requestSource = pipe(dataSource, requestDecode);
+            // convert the request data source into an Observable<T>
+            requestArg = observableFrom(requestSource);
+        }
+        else {
+            // receive a single message for the argument.
+            const requestRx = requestDecode(dataSource);
+            for await (const msg of requestRx) {
+                requestArg = msg;
+                break;
+            }
+        }
+        // Call the implementation.
+        try {
+            const responseObj = methodProto(requestArg);
+            if (!responseObj) {
+                throw new Error('return value was undefined');
+            }
+            if (methodInfo.responseStream) {
+                const responseObs = responseObj;
+                if (!responseObs.subscribe) {
+                    throw new Error('expected return value to be an Observable');
+                }
+                return new Promise((resolve, reject) => {
+                    responseObs.subscribe({
+                        next(value) {
+                            responseSink.push(value);
+                        },
+                        error: (err) => {
+                            responseSink.throw(err);
+                            reject(err);
+                        },
+                        complete: () => {
+                            responseSink.end();
+                            responsePipe.finally(() => {
+                                resolve();
+                            });
+                        },
+                    });
+                });
+            }
+            else {
+                const responsePromise = responseObj;
+                if (!responsePromise.then) {
+                    throw new Error('expected return value to be a Promise');
+                }
+                const responseMsg = await responsePromise;
+                if (!responseMsg) {
+                    throw new Error('expected non-empty response object');
+                }
+                responseSink.push(responseMsg);
+                responseSink.end();
+            }
+        }
+        catch (err) {
+            let asError = err;
+            if (!asError?.message) {
+                asError = new Error('error calling implementation: ' + err);
+            }
+            // mux will return the error to the rpc caller.
+            throw asError;
+        }
+    };
+}
+// createHandler creates a handler from a definition and an implementation.
+export function createHandler(definition, impl) {
+    const methodMap = {};
+    for (const methodInfo of Object.values(definition.methods)) {
+        const methodName = methodInfo.name;
+        let methodProto = impl[methodName];
+        if (!methodProto) {
+            continue;
+        }
+        methodProto = methodProto.bind(impl);
+        methodMap[methodName] = createInvokeFn(methodInfo, methodProto);
+    }
+    return new StaticHandler(definition.fullName, methodMap);
+}

package/dist/srpc/index.d.ts

@@ -1,3 +1,7 @@
-export { Client } from './client';
-export type { OpenStreamFunc } from './stream';
-export { WebSocketConn } from './websocket';
+export type { OpenStreamFunc } from './stream.js';
+export { Client } from './client.js';
+export { Server } from './server.js';
+export { Conn } from './conn.js';
+export { Handler, InvokeFn, createHandler, createInvokeFn } from './handler.js';
+export { Mux, createMux } from './mux.js';
+export { WebSocketConn } from './websocket.js';

package/dist/srpc/index.js

@@ -1,2 +1,6 @@
-export { Client } from './client';
-export { WebSocketConn } from './websocket';
+export { Client } from './client.js';
+export { Server } from './server.js';
+export { Conn } from './conn.js';
+export { createHandler, createInvokeFn } from './handler.js';
+export { createMux } from './mux.js';
+export { WebSocketConn } from './websocket.js';

package/dist/srpc/message.d.ts

@@ -0,0 +1,11 @@
+import * as pbjs from 'protobufjs/minimal';
+import type { Source } from 'it-stream-types';
+export interface MessageDefinition<T> {
+    encode(message: T, writer?: pbjs.Writer): pbjs.Writer;
+    decode(input: pbjs.Reader | Uint8Array, length?: number): T;
+}
+declare type DecodeMessageTransform<T> = (source: Source<Uint8Array | Uint8Array[]>) => AsyncIterable<T>;
+export declare function buildDecodeMessageTransform<T>(def: MessageDefinition<T>): DecodeMessageTransform<T>;
+declare type EncodeMessageTransform<T> = (source: Source<T | T[]>) => AsyncIterable<Uint8Array>;
+export declare function buildEncodeMessageTransform<T>(def: MessageDefinition<T>): EncodeMessageTransform<T>;
+export {};

package/dist/srpc/message.js

@@ -0,0 +1,32 @@
+// buildDecodeMessageTransform builds a source of decoded messages.
+export function buildDecodeMessageTransform(def) {
+    // decodeMessageSource unmarshals and async yields encoded Messages.
+    return async function* decodeMessageSource(source) {
+        for await (const pkt of source) {
+            if (Array.isArray(pkt)) {
+                for (const p of pkt) {
+                    yield* [def.decode(p)];
+                }
+            }
+            else {
+                yield* [def.decode(pkt)];
+            }
+        }
+    };
+}
+// buildEncodeMessageTransform builds a source of decoded messages.
+export function buildEncodeMessageTransform(def) {
+    // encodeMessageSource encodes messages to byte arrays.
+    return async function* encodeMessageSource(source) {
+        for await (const pkt of source) {
+            if (Array.isArray(pkt)) {
+                for (const p of pkt) {
+                    yield* [def.encode(p).finish()];
+                }
+            }
+            else {
+                yield* [def.encode(pkt).finish()];
+            }
+        }
+    };
+}

package/dist/srpc/mux.d.ts

@@ -0,0 +1,11 @@
+import { InvokeFn, Handler } from './handler';
+export interface Mux {
+    register(handler: Handler): void;
+    lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>;
+}
+export declare function createMux(): Mux;
+export declare class StaticMux implements Mux {
+    private services;
+    register(handler: Handler): void;
+    lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>;
+}