Remote Services¶

The client-side surface for consuming a Viper Service over the network. Every class here is a ServiceRemote* type: the handle returned by ServiceRemote.connect and the pool / function objects introspected from it.

The single entry point is ServiceRemote.connect() — everything else is discovered at runtime from the DSM the service embeds. The same handle connects to any Viper service with no per-service codegen. For what a service is, the two pool kinds, and the server side, see Service.

When to use: reach for this family when a Viper service already runs somewhere and this process is its client. Nothing here starts a service.

Note

The server side (Viper::Service, Viper::ServiceServer) is C++ only — it is not part of @digitalsubstrate/dsviper. Node is a client of Viper services.

Quick Start¶

Connect, then dispatch by pool name and function name. No service-specific import:

const { Definitions, ServiceRemote } = require('@digitalsubstrate/dsviper');

const defs = new Definitions();
const s = ServiceRemote.connect('localhost', '54328', defs);

// Resolve a function by pool name + function name, then call it.
const add = s.functionPoolFunc('Tools', 'add');
add.call(32, 10);                      // 42n: an int64 is a bigint

s.close();

functionPoolFunc() resolves one function; functionPools() enumerates them all, each pool answering name(), documentation() and functions(). That is enough to walk a service whose schema this process has never seen — the pools carry the documentation authored in the DSM.

Tip

Python’s binding indexes a pool like a dictionary (s.function_pool_funcs("Tools")["add"](32, 10)). JS has no equivalent on a native handle, so the Node path is functionPoolFunc(pool, name) followed by .call(…). dsviper-node-tools ships service_client.mjs, which builds a pools.Tools.add(…) comfort layer over exactly these calls — the same shape the Python REPL client has.

Key classes¶

Class	Purpose	Example
`ServiceRemote`	The connection to a service, and the root of what it exposes
`ServiceRemoteFunctionPool`	One stateless pool on a connected service
`ServiceRemoteFunction`	A resolved callable, obtained from a pool and a function name
`ServiceRemoteAttachmentFunctionPool`	One stateful pool on a connected service

The mirror of this page for the Python binding is Remote Services.

Connection¶

Class	Description
`ServiceRemote`	The connection to a service, and the root of what it exposes

Stateless Pools¶

Class	Description
`ServiceRemoteFunctionPool`	A pool whose functions take only the parameters they declare
`ServiceRemoteFunctionPoolFunctions`	An opaque handle on one pool of a service, answered by functionPoolFuncs(pool): its presence says the service serves the pool
`ServiceRemoteFunctionPoolFunction`	The declaration of one function in a pool: its prototype and documentation
`ServiceRemoteFunction`	A resolved callable, answered by ServiceRemote.functionPoolFunc(poolIdOrName, name)

Stateful Pools¶

Class	Description
`ServiceRemoteAttachmentFunctionPool`	A pool whose functions take the state they run on as first argument
`ServiceRemoteAttachmentFunctionPoolFunctions`	An opaque handle on one attachment pool of a service, answered by attachmentFunctionPoolFuncs(poolIdOrName): its presence says the service serves the pool
`ServiceRemoteAttachmentFunctionPoolFunction`	The declaration of one attachment function
`ServiceRemoteAttachmentFunction`	A resolved attachment callable, answered by ServiceRemote.attachmentFunctionPoolFunc(poolIdOrName, name)

Reference¶

class ServiceRemote()¶

The connection to a service, and the root of what it exposes.

The pools and functions are discovered from the definitions the service carries, so no per-service code is needed. Use connect(…), or connectLocal(…) for a unix socket.

This is the CLIENT half, and the only half. Nothing here stands a service up: the functions a pool exposes are registered in C++, so the other end is built and run outside this package. Without one listening, connect throws.

Note: Not directly instantiable.

exported from index.d

ServiceRemote.[Symbol․dispose]()¶: Release the resource at scope exit via using (TC39 disposable); delegates to close(). Idempotent.

ServiceRemote.attachmentFunctionPoolFunc(poolIdOrName, name)¶

Return one callable function by pool and name; throws if the pool or function is unknown.

Arguments:

poolIdOrName (string | ValueUUId)
name (string)

Returns:

ServiceRemoteAttachmentFunction

ServiceRemote.attachmentFunctionPoolFuncs(poolIdOrName)¶

Return the callable functions of an attachment pool, or undefined.

The pool is the one poolIdOrName names; undefined means the service serves no such pool.

poolIdOrName is a uuid or a name.

Arguments:

poolIdOrName (string | ValueUUId)

Returns:

ServiceRemoteAttachmentFunctionPoolFunctions | undefined

ServiceRemote.attachmentFunctionPools()¶

Return the list of ServiceRemoteAttachmentFunctionPool.

Returns:: ServiceRemoteAttachmentFunctionPool[]

ServiceRemote.close()¶: Close the connection; the service at the other end keeps running.

ServiceRemote.definitions()¶

Return the Definitions the service and this client agree on.

Returns:: DefinitionsConst

ServiceRemote.functionPoolFunc(poolIdOrName, name)¶

Return one callable function by pool and name; throws if the pool or function is unknown.

Arguments:

poolIdOrName (string | ValueUUId)
name (string)

Returns:

ServiceRemoteFunction

ServiceRemote.functionPoolFuncs(poolIdOrName)¶

Return the callable functions of a pool, or undefined.

The pool is the one poolIdOrName names; undefined means the service serves no such pool.

poolIdOrName is a uuid or a name.

Arguments:

poolIdOrName (string | ValueUUId)

Returns:

ServiceRemoteFunctionPoolFunctions | undefined

ServiceRemote.functionPools()¶

Return the list of ServiceRemoteFunctionPool.

Returns:: ServiceRemoteFunctionPool[]

ServiceRemote.isClosed()¶

Return true once the connection is closed.

Returns:: boolean

ServiceRemote.peername()¶

Return the address of the service at the other end.

Returns:: string

ServiceRemote.sockname()¶

Return the address of this end of the connection.

Returns:: string

ServiceRemote.toDsmDefinitions()¶

Return the DSMDefinitions of the service.

Returns:: DSMDefinitions

static ServiceRemote.connect(host, service, definitions)¶

Return a ServiceRemote connected to host on service.

definitions is extended in place with the service’s own, so an empty new Definitions() is enough: after the call it holds the types the service’s functions take. service is the port the server listens on, a number or a service name as a string; there is no default, the host that runs the service chooses it.

Throws ViperError when nothing answers on host and service.

Arguments:

host (string)
service (string)
definitions (Definitions)

Returns:

ServiceRemote

static ServiceRemote.connectLocal(socketPath, definitions)¶

Return a ServiceRemote connected to socketPath, typed by definitions.

definitions is extended in place with the service’s own, as connect does.

Arguments:

socketPath (string)
definitions (Definitions)

Returns:

ServiceRemote

class ServiceRemoteFunctionPool()¶

A pool whose functions take only the parameters they declare.

Its name, uuid, documentation, and the functions it declares.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteFunctionPool.check(funcName)¶

Return the declaration of the function named funcName, or throw if the pool has: none.

Arguments:

funcName (string)

Returns:

ServiceRemoteFunctionPoolFunction

ServiceRemoteFunctionPool.documentation()¶

Return the documentation the service gives the pool, empty when it gives none.

Returns:: string

ServiceRemoteFunctionPool.functions()¶

Return the list of function declarations.

Returns:: ServiceRemoteFunctionPoolFunction[]

ServiceRemoteFunctionPool.name()¶

Return the pool name as declared.

Returns:: string

ServiceRemoteFunctionPool.query(funcName)¶

Return the declaration of the function named funcName, or undefined if the pool has: none.

Arguments:

funcName (string)

Returns:

ServiceRemoteFunctionPoolFunction | undefined

ServiceRemoteFunctionPool.uuid()¶

Return the uuid the pool is registered under.

Returns:: ValueUUId

class ServiceRemoteFunctionPoolFunctions()¶

An opaque handle on one pool of a service, answered by functionPoolFuncs(pool): its

presence says the service serves the pool. It offers no lookup - take a function with ServiceRemote.functionPoolFunc(poolIdOrName, name).

Note: Not directly instantiable.

exported from index.d

class ServiceRemoteFunctionPoolFunction()¶

The declaration of one function in a pool: its prototype and

documentation. It describes the function; ServiceRemoteFunction calls it.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteFunctionPoolFunction.documentation()¶

Return the documentation the service gives the function, empty when it gives none.

Returns:: string

ServiceRemoteFunctionPoolFunction.prototype()¶

Return the FunctionPrototype: the name, the parameters and the return type.

Returns:: FunctionPrototype

class ServiceRemoteFunction()¶

A resolved callable, answered by ServiceRemote.functionPoolFunc(poolIdOrName, name).

Call it through call(…args), the object itself not being callable: the arguments are checked against the prototype, and the result is a native leaf, or a wrapped Value for a container or a blob. Calling once the connection is closed throws ViperError.

It also answers which service, pool and declaration it came from.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteFunction.call(...args)¶

Call the remote function and return its result (a native leaf, or a wrapped Value for a: container / blob - the encoded projection). Args are checked against the prototype.

Arguments:

args (InputValue[])

Returns:

OutputValue

ServiceRemoteFunction.function()¶

Return the declaration of the function being called.

Returns:: ServiceRemoteFunctionPoolFunction

ServiceRemoteFunction.pool()¶

Return the pool the function belongs to.

Returns:: ServiceRemoteFunctionPool

ServiceRemoteFunction.service()¶

Return the ServiceRemote the call goes through.

Returns:: ServiceRemote

class ServiceRemoteAttachmentFunctionPool()¶

A pool whose functions take the state they run on as first argument.

A CommitAttachmentMutating for a function that mutates, an AttachmentGetting for one that only reads. The caller supplies that state on every call; the pool holds none.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunctionPool.check(funcName)¶

Return the declaration of the attachment function named funcName, or throw if: the pool has none.

Arguments:

funcName (string)

Returns:

ServiceRemoteAttachmentFunctionPoolFunction

ServiceRemoteAttachmentFunctionPool.documentation()¶

Return the documentation the service gives the pool, empty when it gives none.

Returns:: string

ServiceRemoteAttachmentFunctionPool.functions()¶

Return the list of function declarations.

Returns:: ServiceRemoteAttachmentFunctionPoolFunction[]

ServiceRemoteAttachmentFunctionPool.name()¶

Return the pool name as declared.

Returns:: string

ServiceRemoteAttachmentFunctionPool.query(funcName)¶

Return the declaration of the attachment function named funcName, or undefined: if the pool has none.

Arguments:

funcName (string)

Returns:

ServiceRemoteAttachmentFunctionPoolFunction | undefined

ServiceRemoteAttachmentFunctionPool.uuid()¶

Return the uuid the pool is registered under.

Returns:: ValueUUId

class ServiceRemoteAttachmentFunctionPoolFunctions()¶

An opaque handle on one attachment pool of a service, answered by

attachmentFunctionPoolFuncs(poolIdOrName): its presence says the service serves the pool. It offers no lookup - take a function with ServiceRemote.attachmentFunctionPoolFunc(poolIdOrName, name).

Note: Not directly instantiable.

exported from index.d

class ServiceRemoteAttachmentFunctionPoolFunction()¶

The declaration of one attachment function.

Its prototype, its documentation, and whether it mutates the state it is given. It describes the function; ServiceRemoteAttachmentFunction calls it.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunctionPoolFunction.documentation()¶

Return the documentation the service gives the function, empty when it gives none.

Returns:: string

ServiceRemoteAttachmentFunctionPoolFunction.isMutable()¶

Return true if the function mutates the state it is given.

Returns:: boolean

ServiceRemoteAttachmentFunctionPoolFunction.prototype()¶

Return the FunctionPrototype: the name, the parameters and the return type.

Returns:: FunctionPrototype

class ServiceRemoteAttachmentFunction()¶

A resolved attachment callable, answered by

ServiceRemote.attachmentFunctionPoolFunc(poolIdOrName, name).

Call it through call(state, …args), the object itself not being callable: the state it runs on first, then the parameters the prototype declares - one argument more than function().prototype() reports. A function that mutates takes a CommitAttachmentMutating; one that only reads takes an AttachmentGetting as well. Anything else as the first throws TypeError.

The function runs on the service, and the state stays here: the service drives it back over the connection while the call runs, so what it holds is read and written in place. That state is a context you own - nothing is persisted unless you carry it into a database yourself.

The result is a native leaf, or a wrapped Value for a container or a blob. Calling once the connection is closed throws ViperError.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunction.call(attachmentGetting, ...args)¶

Call the remote attachment function and return its result (a native leaf, or a wrapped: Value for a container / blob). The state the service reads and writes comes first: a function that mutates takes a CommitAttachmentMutating, one that only reads takes an AttachmentGetting as well. The args are checked against the prototype.

Arguments:

attachmentGetting (AttachmentGetting)
args (InputValue[])

Returns:

OutputValue

ServiceRemoteAttachmentFunction.function()¶

Return the declaration of the function being called.

Returns:: ServiceRemoteAttachmentFunctionPoolFunction

ServiceRemoteAttachmentFunction.pool()¶

Return the pool the function belongs to.

Returns:: ServiceRemoteAttachmentFunctionPool

ServiceRemoteAttachmentFunction.service()¶

Return the ServiceRemote the call goes through.

Returns:: ServiceRemote