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);                      // 42

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`	One stateless pool on a connected service
`ServiceRemoteFunctionPoolFunctions`	The functions of one pool, reached by attribute: service.pools.Tools.add
`ServiceRemoteFunctionPoolFunction`	The declaration of one function in a pool: its prototype and documentation
`ServiceRemoteFunction`	A resolved callable, obtained from a pool and a function name

Stateful Pools¶

Class	Description
`ServiceRemoteAttachmentFunctionPool`	One stateful pool on a connected service
`ServiceRemoteAttachmentFunctionPoolFunctions`	The functions of one attachment pool a service serves, reached by attribute
`ServiceRemoteAttachmentFunctionPoolFunction`	The declaration of one attachment function
`ServiceRemoteAttachmentFunction`	A resolved attachment callable, obtained from a pool and a function 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 the static factory method connect(…).

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 a list of pools.

Returns:: ServiceRemoteAttachmentFunctionPool[]

ServiceRemote.close()¶: Close the service.

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 a list of pools.

Returns:: ServiceRemoteFunctionPool[]

ServiceRemote.isClosed()¶

Return true if the service 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, typed by definitions.

Arguments:

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

Returns:

ServiceRemote

static ServiceRemote.connectLocal(socketPath, definitions)¶

Return a ServiceRemote connected to socketPath, typed by definitions.

Arguments:

socketPath (string)
definitions (Definitions)

Returns:

ServiceRemote

class ServiceRemoteFunctionPool()¶

One stateless pool on a connected service.

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

Note: Not directly instantiable.

exported from index.d

ServiceRemoteFunctionPool.check(funcName)¶

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

Arguments:

funcName (string)

Returns:

ServiceRemoteFunctionPoolFunction

ServiceRemoteFunctionPool.documentation()¶

Return the doc comment written on the pool where it was declared.

Returns:: string

ServiceRemoteFunctionPool.functions()¶

Return the list of functions.

Returns:: ServiceRemoteFunctionPoolFunction[]

ServiceRemoteFunctionPool.name()¶

Return the pool name as declared.

Returns:: string

ServiceRemoteFunctionPool.query(funcName)¶

Return 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()¶

The functions of one pool, reached by attribute: service.pools.Tools.add.

A lookup container, not a function itself.

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 doc comment written on the function where it was declared.

Returns:: string

ServiceRemoteFunctionPoolFunction.prototype()¶

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

Returns:: FunctionPrototype

class ServiceRemoteFunction()¶

A resolved callable, obtained from a pool and a function name. Call it like a function;

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()¶

One stateful pool on a connected service.

Like a function pool, but its functions operate on attachments and take a state as their first argument.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunctionPool.check(funcName)¶

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

Arguments:

funcName (string)

Returns:

ServiceRemoteAttachmentFunctionPoolFunction

ServiceRemoteAttachmentFunctionPool.definitions()¶

Returns:: DefinitionsConst

ServiceRemoteAttachmentFunctionPool.documentation()¶

Return the doc comment written on the pool where it was declared.

Returns:: string

ServiceRemoteAttachmentFunctionPool.functions()¶

Return the list of functions.

Returns:: ServiceRemoteAttachmentFunctionPoolFunction[]

ServiceRemoteAttachmentFunctionPool.name()¶

Return the pool name as declared.

Returns:: string

ServiceRemoteAttachmentFunctionPool.query(funcName)¶

Return 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()¶

The functions of one attachment pool a service serves, reached by attribute.

A lookup container, not a function itself. Calls cross the connection.

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.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunctionPoolFunction.documentation()¶

Return the doc comment written on the function where it was declared.

Returns:: string

ServiceRemoteAttachmentFunctionPoolFunction.isMutable()¶

Return true if the function is mutable.

Returns:: boolean

ServiceRemoteAttachmentFunctionPoolFunction.prototype()¶

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

Returns:: FunctionPrototype

class ServiceRemoteAttachmentFunction()¶

A resolved attachment callable, obtained from a pool and a function name.

Call it with a state as its first argument.

Note: Not directly instantiable.

exported from index.d

ServiceRemoteAttachmentFunction.call(...args)¶

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

Arguments:

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