network-services

Network⬄Services

A type-safe asynchronous RPC Service facility for connecting your apps to the network.

Introduction

Network-Services provides a simple and intuitive toolkit that makes connecting your app to the network easy. You can use Network-Services to transform your application into a network connected Service App. You can connect to your Service App, from the same process or another process, and call methods on it using a type-safe Service API.

A Service can be explained with a complete and simple example. In the "Hello, world!" example shown below, a Greeter Service App is hosted on 127.0.0.1:3000 and its Greeter.greet method is called over a net.Socket using a Service API of type Greeter.

Features

• A type-safe API facility: code completion, parameter types, and return types.
• Return values and Errors are marshalled back to the caller.
• Infinite property nesting; you can use a Service API to call nested properties on a Service App at any depth.
• Bi-directional asynchronous RPC over TCP.
• Security can be implemented using the native Node TLS module (i.e., TLS and Client Certificate Authentication).
• A configurable message protocol. You can marshal your messages however you choose (e.g., JSON, binary, etc.), or use the default minimalist JSON message protocol.
• Extend Network-Services using the native stream.Duplex interface.

Table of Contents

• Concepts
  • Service
  • Service App
  • Service API
• Usage
• API
• Type Safety
• Examples
  • An instance of Hello, World!
  • Use Network-Services to create bi-directional type safe APIs.
  • Use Network-Services with TLS Encryption and Client Certificate Authentication.
  • Use Network-Services to create an API with a nested method.
• Message Protocol
  • Default JSON Message Protocol
• Extend Network-Services
• Security
  • Use TLS encryption.
  • Use TLS client certificate authentication.
  • Restrict API calls at runtime.
  • Specify an ingressQueueLimit and egressQueueLimit in the Service options.
• Best Practices
  • Create a TypeScript interface for your Service API.
  • Set a timeout in ServiceAPIOptions.
  • Impose property path restrictions.
  • Ensure your stream.Duplex (e.g., a net.Socket) is ready for use.
  • If you create a stream (e.g., a net.Socket), set an error handler on it.
  • Close and dereference streams in order to prevent memory leaks.

Concepts

Network-Services features an intuitive API that can be most easily understood by looking at an example or common usage. There are three important concepts that comprise the API, a Service, a Service App, and a Service API.

Service

A Service instance coordinates bi-directional communication over a stream.Duplex (e.g., a net.Socket). Once a Service is instantiated it can be used in order to create a Service App or a Service API. You can create a Service using the createService helper function.

Service App

A Service App is a user defined object instance (i.e., an instance of your application) that is connected to a Service API over a stream.Duplex (e.g., a net.Socket). You can use the service.createServiceApp<T> helper function, with your app as its argument, in order to create a Service App. Once a Service App is instantiated, its methods can be called using a Service API instantiated in the same or different process.

Service API

A Service API is a type safe representation of your remote Service App. You can create a Service API using the service.createServiceAPI<T> helper function. service.createServiceAPI<T> will return a Proxy that is type cast in order to make the methods that comprise <T> suitable for making asynchronous function calls. You can call methods on the Service API object much how you would call methods on an instance of <T> itself.

Usage

Using Network-Services involves creating a Service App and calling its methods over a stream (e.g., net.Socket) using a Service API. In this example you will create a Greeter Service and call its Greeter.greet method over a net.Socket using an asynchronous Service API of type Greeter.

How to create a Hello World Greeter Service.

Import the node:net module and the createService helper function.

import * as net from "node:net";
import { createService } from 'network-services';

Create a Greeter Application.

class Greeter {
    greet(kind: string) {
        return `Hello, ${kind} world!`;
    }
}
const greeter = new Greeter();

Create a Server and create a Greeter Service App that is connected to the network.

const server = net.createServer().listen({ port: 3000, host: '127.0.0.1' });
server.on('connection', (socket: net.Socket) => {
    const service = createService(socket);
    service.createServiceApp(greeter); // Greeter.greet can now be called over the `net.Socket` using a Service API.
});

Connect to the Server and create a Service API of type Greeter.

Use the greeter Service API in order to call the remote Service App's methods and log the greeting.

const socket = net.connect({ port: 3000, host: '127.0.0.1' });
socket.on('ready', async () => {
    const service = createService(socket);
    const greeter = service.createServiceAPI<Greeter>(); // Create a Service API of type Greeter.
    const greeting = await greeter.greet('happy'); 
    //                            ^
    // The `greeter` object facilitates code completion, parameter types and return types.
    console.log(greeting); // Hello, happy world!
});

Please see the Hello World example for a working implementation.

In the Hello World example communication is uni-directional (i.e., a request-response architecture). Please see the bi-directional type safe APIs example for an example of bi-directional communication.

API

network-services.createService(stream, options)

• stream <stream.Duplex> A stream.Duplex (e.g., a net.Socket). The stream.Duplex will be used for bi-directional communication between Service Apps and Service APIs.
• options <ServiceOptions & MuxOptions>
  • ingressQueueSizeLimit <number> An optional ingress buffer size limit in bytes. This argument specifies the limit on buffered data that may accumulate from calls from the remote Service API and return values from the remote Service App. If the size of the ingress buffer exceeds this value, the stream will emit a QueueSizeLimitError and close. Default: undefined (i.e., no limit).
  • egressQueueSizeLimit <number> An optional egress buffer size limit in bytes. This argument specifies the limit on buffered data that may accumulate from calls to the remote Service App and return values to the remote Service API. If the size of the egress buffer exceeds this value, a QueueSizeLimitError will be thrown and the stream will close. Default: undefined (i.e., no limit).
  • muxClass <MuxConstructor> An optional Mux implementation. Messages are muxed as they enter and leave the stream.Duplex. You can use one of the default muxers or provide a custom implementation. For example, you can extend the default network-services.BufferMux and override the serializeMessage and deserializeMessage methods in order to implement a custom message protocol (e.g., a binary message protocol). If a custom Mux implementation is not provided here, Network-Services will provide a default Mux implementation compatible with the underlying stream.Duplex. Default muxers respect back-pressure. Default: a BufferMux or a ObjectMux for streams in object mode.
• Returns: <Service>

service.createServiceApp<T>(app, options)

• app <object> An instance of your application.

• options <ServiceAppOptions<T>>

  • paths <Array<PropPath<Async<T>>>> An Array of property paths (i.e., dot-path strings). If defined, only property paths in this list may be called on the Service App. Each element of the Array is a PropPath and a PropPath is simply a dot-path string representation of a property path. Please see the Nested Method example for a working example. Default: undefined.

• Returns: <ServiceApp<T>>

service.createServiceAPI<T>(options)

• options <ServiceAPIOptions>

  • timeout <number> Optional argument in milliseconds that specifies the timeout for function calls. Default: undefined (i.e., no timeout).
  • identifierGenerator <IdentifierGenerator> An optional instance of a class that implements the network-services.IdentifierGenerator interface. This class instance will be used in order to generate an unique identifier for each API call. The default network-services.NumericIdentifierGenerator will work for the common case; however, a more robust solution may be required for certain custom net.Duplex implementations. Default: network-services.NumericIdentifierGenerator

• Returns: <Async<T>> A Proxy of type <T> that consists of asynchronous analogues of methods in <T>.

The service.createServiceAPI<T> helper function returns a JavaScript Proxy object cast to type <Async<T>>. service.createServiceAPI<T> filters and transforms the function types that comprise <T> into their asynchronous analogues i.e., if a function type isn't already defined as returning a Promise, it will be transformed to return a Promise - otherwise its return type will be left unchanged. This transformation is necessary because all function calls over a stream.Duplex (e.g., a net.Socket) are asynchronous. Please see the Bi-directional Type Safe APIs example for how to easily consume a <Async<T>> in your application.

The following Errors may arise when a Service API method is called:

• Errors:
  • If the remote Service App method throws an Error, the Error will be marshalled back from the Service and the Promise will reject with the Error as its reason.
  • If a call exceeds the egressQueueSizeLimit, the Promise will reject with QueueSizeLimitError as its reason and the stream will close.
  • If an error event occurs on the stream.Duplex, the Promise will reject with the given reason.
  • If the stream.Duplex closes, the Promise will reject with StreamClosedError as its reason.
  • If the paths Array is defined in the remote ServiceAppOptions<T> and a method is called that is not a registered property path, the Promise will reject with PropertyPathError as its reason.
  • If a property is invoked that is not a function on the remote Service App, the Promise will reject with TypeError as its reason.
  • If the call fails to resolve or reject prior to the timeout specified in ServiceAPIOptions, the Promise will reject with CallTimeoutError as its reason.

NB The Service API and type safety is not enforced at runtime. Please see the paths property of the ServiceAppOptions<T> object for runtime checks.

Type Safety

Network-Services provides a facility for building a type safe network API. The type safe API facility is realized through use of JavaScript's Proxy object and TypeScript's type variables. A Proxy interface is created by passing your app's public interface to the type parameter of the service.createServiceAPI<T> helper function. The type safe Proxy interface facilitates code completion, parameter types, and return types; it helps safeguard the integrity of your API.

Please see the Bi-directional Type Safe APIs example for a working implementation.

Examples

An instance of Hello, World! ^(example)

Please see the Usage section above or the Hello, World! example for a working implementation.

Use Network-Services to create bi-directional type safe APIs. ^(example)

Please see the Bi-directional Type Safe APIs example for a working implementation.

Use Network-Services with TLS Encryption and Client Certificate Authentication. ^(example)

Please see the TLS Encryption and Client Authentication example for a working implementation.

Use Network-Services to create an API with a nested method. ^(example)

Please see the Nested Method example for a working implementation.

Message Protocol

Network-Services provides a default minimalist JSON message protocol. However, you can marshal your messages however you choose by extending the BufferMux class and implementing theserializeMessage and deserializeMessage methods. Simply pass your custom Mux implementation in the ServiceOptions when you create your Service. Please see the muxClass parameter in ServiceOptions of the createService helper function.

Default JSON Message Protocol

Network-Services provides a concise default JSON message protocol. The message protocol is guided by parsimony; it includes just what is needed to make a function call and return a result or throw an Error.

Marshalling

Arguments, return values, and Errors are serialized using JavaScript's JSON.stringify. The choice of using JSON.stringify has important and certain ramifications that should be understood. Please see the rules for serialization.

Type Definitions

The type definitions for the default JSON message protocol:

The Call Message

A CallMessageList consists of a numeric message type, the call identifier, the property path to the called function, and its arguments.

type CallMessageList = [
    0, // The message type; 0 = Call.
    string, // The call identifier.
    Array<string>, // The elements of the property path to the called method.
    ...Array<unknown> // The arguments to be passed to the function.
];

The Result Message

A ResultMessageList consists of a numeric message type, the call identifier, and a return value or Error.

type ResultMessageList = [
    1 | 2, // The message type; 1 = Error, 2 = Result.
    string, // The call identifier.
    unknown // The return value or Error.
];

Extend Network-Services

Network-Services is modeled around communication over net.Sockets; however, it can be used in order to communicate over any resource that implements the stream.Duplex interface. This means that if you can model your bi-directional resource as a stream.Duplex, it should work with Network-Services. The createService helper function takes a stream.Duplex as its first argument. Just implement a stream.Duplex around the resource and pass it into the createService helper function.

Security

Security is a complex and multifaceted endeavor.

Use TLS encryption.

TLS Encryption may be implemented using native Node.js TLS Encryption. Please see the TLS Encryption and Client Authentication example for a working implementation.

Use TLS client certificate authentication.

TLS Client Certificate Authentication may be implemented using native Node.js TLS Client Authentication. Please see the TLS Encryption and Client Authentication example for a working implementation.

Restrict API calls at runtime.

The Service API and type safety are not enforced at runtime. You can restrict API calls to specified Service App methods by providing an Array of property paths to the paths property of the ServiceAppOptions<T> object. If the paths Array is defined in ServiceAppOptions<T> and a method is called that is not a registered property path, the awaited Promise will reject with PropertyPathError as its reason.

Specify an ingressQueueSizeLimit and egressQueueSizeLimit in the Service options.

Network-Services respects backpressure; however, it is advisable to specify how much data may be buffered in order to ensure your application can respond to adverse network phenomena. If the stream peer reads data at a rate that is slower than the rate that data is written to the stream, data may buffer until memory is exhausted. This is a vulnerability that is inherent in streams, which can be mitigated by preventing internal buffers from growing too large.

You can specify a hard limit on ingress and egress buffers in the Service options. ingressQueueSizeLimit specifies a limit on incoming data i.e., data returned from the remote Service App or calls from the remote Service API. egressQueueSizeLimit specifies a limit on outgoing data i.e., data returned to the remote Service API or calls to the remote Service App. If an ingress or egress buffer exceeds the specified limit, the respective stream will error and close. Network-Services will immediately tear down its internal buffers in order to free memory - dereference the stream, and GC will sweep.

Best Practices

Create a TypeScript interface for your Service API.

You can pass your application's class as a type variable argument to the service.createServiceAPI<T> helper function; however, it's advisable to define a public interface instead. You can publish your public interface to be consumed separately or export it from your application.

For example, for the Greeter class in the "Hello, World!" example, the interface:

interface IGreeter {
    greet(kind: string): string
}

Set a timeout in ServiceAPIOptions.

Calling a method on a remote Service App using a Service API may take too long to resolve or reject - or may never resolve at all. This effect can be caused by a long running operation in the remote Service App or a congested network. If the call fails to resolve or reject prior to the timeout specified in ServiceAPIOptions, the Promise will reject with CallTimeoutError as its reason.

Impose property path restrictions.

Unless you control the definition of both the Service API and the Service App, you should specify which methods may be called on your Service App using the paths property of ServiceAppOptions<T>.

Ensure your stream.Duplex (e.g., a net.Socket) is ready for use.

Network-Services assumes that the stream.Duplex passed to createService is ready to use; this assumption and separation of concern is an intentional design decision. A stream.Duplex implementation (e.g., a net.Socket) may include an event (e.g., something like 'ready' or 'connect') that will indicate it is ready for use. Please await this event, if available, prior to passing the stream.Duplex to the createService helper function.

If you create a stream (e.g., a net.Socket), set an error handler on it.

A stream.Duplex may error before becoming ready; hence, as usual, you should synchronously set an error handler on a new stream instance.

Close and dereference streams in order to prevent memory leaks.

The object graph of a Service instance is rooted on its stream. It will begin decomposition immediately upon stream closure. However, in order to fully dispose of a Service instance, simply destroy and dereference its stream; GC will sweep buffers and other liminal resources.