Anatomy of a Service

A Viper::Service aggregates DSM definitions and function pools into an immutable container that can be exposed over a network socket. The Transparent Remote Access principle of the Viper runtime means a remote call has the shape of a local one — same functions, same arguments, same state passed in — and the network is hidden by the runtime.

Which side a language can play differs. A pool is implemented and hosted in C++. The generated Python and TypeScript packages call a pool only through a service, with the pool’s Remote over a ServiceRemote; the Pool of a Python package’s <pool>.embedded module, its host side, wraps a pool that a C++ host application hands to its embedded Python, and the package cannot build one on its own.

Two pool types

A service exposes two kinds of typed pool, each with distinct execution semantics.

FunctionPool — stateless

Groups stateless functions that execute on the server and return a value. Pure functions: same inputs, same outputs, no access to storage or mutable state.

"""This pool provides utility functions."""
function_pool Tools {7aa5aea2-c9de-4f91-8371-7995aca8c947} {
int64   add(int64 a, int64 b);
Vector3 addVector(Vector3 a, Vector3 b);
string  randomString(uint32 size);
};
  • Stateless — no CommitAttachmentMutating, no backing storage, no side effects on persisted data.

  • Immediate — execute synchronously, return immediately.

  • Type-safe — parameters and return value validated through the generated FunctionPrototype.

AttachmentFunctionPool — stateful

Groups functions that operate inside a stateful context: the state the client passes at call time, read through an AttachmentGetting, and written through a CommitAttachmentMutating by the functions declared mutable.

"""This pool provides Player utility functions."""
attachment_function_pool PlayerModel { d75a8a57-... } {
mutable key<Player> create(string nickname, Level level);
optional<key<Player>> hasPlayer(string nickname);
};
  • Stateful — each call takes a state passed by the client at call time.

  • mutable — a function marked mutable in the DSM takes a CommitAttachmentMutating and may write; a function without it (hasPlayer above) takes an AttachmentGetting and only reads.

  • AttachmentGetting and CommitAttachmentMutating are the protocol, not the storage. The service has no opinion on what backs the interface — the client picks the implementation that fits its scenario, and the service reads from / writes to it through the interface alone.

Server side — assembling and serving

A service binary is small: it composes pools into a Viper::Service, opens a socket, and runs Viper::ServiceServer.

The canonical worked example lives in the service/ directory of the devkit-codegen-test repository, dedicated to exercising the pool codegen end to end. Its kibo.toml generates a C++ server side and a client side in C++, Python and TypeScript with kibo-project (see kibo-project): the C++ and Python targets ask for both sides of both kinds of pool — Pool, PoolRemote, AttachmentPool, AttachmentPoolRemote — and the TypeScript target for the client side only, PoolRemote and AttachmentPoolRemote. From service/cpp/src/ServiceServer.cpp, abridged:

// 1) Compose the service from definitions and pools.
auto const service{
    Viper::Service::make(
        service::codec::definitions(),
        {                                      // FunctionPools
            service::tools::pool(),
        },
        {                                      // AttachmentFunctionPools
            service::player_model::pool()
        })
};

// 2) Open a server socket — TCP or Unix.
serverSocket = Viper::Socket::makePassiveInet(inetAddress, inetPort);

// 3) Run the service (blocking).
Viper::ServiceServer::run(serverSocket, service, logging, cancelation);

The laboratory builds this server as build/service/cpp/service_server (the service_server target of its CMake project, which service/cpp/run_test.sh builds with cmake -S . -B build && cmake --build build --target service_server from the repository root). It listens on TCP with -a <address> -p <port>, or on a local socket with -s <socket path>, and serves until stopped:

build/service/cpp/service_server -a localhost -p 54328

The clients below connect to localhost:54328.

Three things to note:

  • service::codec::definitions() is the embedded DSM — generated by Kibo from the service’s DSM definitions, shipped inside the binary so that connecting clients can discover the typed surface at connect time without prior knowledge of the schema.

  • service::tools::pool() and service::player_model::pool() are generated by the Pool and AttachmentPool features, one namespace per pool: each returns the Viper::FunctionPool (or Viper::AttachmentFunctionPool) that registers the functions the pool declares. The functions themselves are declared in that namespace and implemented by hand — cpp/src/ToolsPoolBridges.cpp and cpp/src/PlayerModelPoolBridges.cpp hold the actual business logic (see C++, Pools).

  • A service binary can also pair with a UI application by reusing the same pool instances the UI process composes — same business surface, no UI tier. The UI process and the service binary then share the generated pools and their implementations, and publish those pools through different surfaces (in-process API on one side, RPC on the other).

Client side — Dual Reality

The C++, Python and TypeScript clients consume the same Viper RPC protocol through the Dual Reality pattern: an adapter between Viper’s dynamic, metadata-driven runtime and the static API world where developers and IDEs are most productive.

Two paths reach the same RPC layer:

  • Dynamic — a generic universal client that introspects any Viper C++ service at connect time and dispatches calls through a runtime dictionary. No per-service codegen, ever.

  • Static — per-pool typed proxies generated by Kibo from the service’s DSM. Their only purpose is developer / IDE comfort — autocompletion, compile-time type checking, jump-to-definition. They wrap the same dynamic dispatch underneath.

The dynamic path — one universal generic client, zero per-service codegen

Viper::ServiceRemote::connect(...) returns a handle that exposes each pool’s functions as a runtime-introspected dictionary. This path works without importing any service-specific generated module — the same client connects to any Viper C++ service:

# Pure dynamic call — no per-service codegen needed
from dsviper import Definitions, ServiceRemote

defs = Definitions()
s = ServiceRemote.connect("localhost", "54328", defs)

result = s.function_pool_funcs("Tools")["add"](32, 10)  # returns 42

The minimal connection scaffold ships with dsviper-tools as service_client.py — five lines from which any diagnostic, REPL exploration, or schema-agnostic adapter extends.

The static Python path — Kibo-generated typed proxies

With the PoolRemote and AttachmentPoolRemote features, each pool’s client side is a module of the pool’s subpackage, imported by its path (service.tools.remote, service.player_model.remote). Its Remote class is a thin typed proxy over the dynamic dispatch: function_pool_funcs(...) for a function_pool, attachment_function_pool_funcs(...) for an attachment_function_pool.

From service/python/src/client.py, abridged:

import dsviper

from service.demo import Vector3, Level, commit_attachments
from service.player_model.remote import Remote as PlayerModelRemote
from service.tools.remote import Remote as ToolsRemote

defs = dsviper.Definitions()
service_remote = dsviper.ServiceRemote.connect(address, port, defs)

# Stateless — the typed proxy of the pool Tools.
tools = ToolsRemote(service_remote)
if tools.is_available():
    print(f"add(32,10) -> {tools.add(32, 10)}")

    v1 = Vector3({"x": 1, "y": 2, "z": 3})
    v2 = Vector3({"x": 10, "y": 20, "z": 30})
    print(f"add_vector(v1,v2) -> {tools.add_vector(v1, v2)}")

# Stateful — the typed proxy of the pool PlayerModel. The client passes the
# CommitAttachmentMutating it wants to use as the receptacle; execution runs on the
# SERVER, and mutations land in the CLIENT-LOCAL `mutating` via the
# Remote-Local protocol below.
player_model = PlayerModelRemote(service_remote)
if player_model.is_available():
    state = dsviper.CommitState(defs.const())
    mutable = dsviper.CommitMutableState(state)
    mutating = mutable.attachment_mutating()
    getting = mutable.attachment_getting()

    nickname = "the shadow man"
    key = player_model.create(mutating, nickname, Level.BEGINNER)

    if found := player_model.has_player(getting, nickname):
        if document := commit_attachments.Player.property.get(getting, found.unwrap()):
            player = document.unwrap()
            print(f"nickname={player.nickname}, level={player.level}")

The state is built over defs, the Definitions given to connect: that works because connect() fills it with the service’s model, so the state knows the attachments the pool writes. A state over empty definitions fails on the first write with an unregistered attachment error; the package’s own service.definitions() works too. create is mutable and takes the CommitAttachmentMutating; has_player only reads and takes an AttachmentGetting — here the mutable state’s, which sees what create wrote.

Python spells a pool function in snake_case (add_vector, has_player); the Remote calls the function under its DSM name. See Python, Pools.

The static C++ path — Kibo-generated typed proxies

Symmetric to Python, with the PoolRemote and AttachmentPoolRemote features: one header per pool, service_tools_remote.hpp and service_player_model_attachment_remote.hpp, each declaring a Remote class in the pool’s namespace. A client can select them without Pool and AttachmentPool. From service/cpp/src/ServiceClient.cpp, abridged:

#include "service_player_model_attachment_remote.hpp"
#include "service_tools_remote.hpp"
#include "service_demo_commit_attachments.hpp"

auto const definitions{Viper::Definitions::make()};
auto const service{Viper::ServiceRemote::connect(inetAddress, inetPort, definitions)};

// Stateless call — typed C++ proxy.
auto const tools{service::tools::Remote{service}};
if (tools.isAvailable()) {
    auto const r{tools.add(32, 10)};                          // 42
}

// Stateful call — typed C++ proxy. The client passes its own
// CommitAttachmentMutating receptacle as the call's state.
auto const playerModel{service::player_model::Remote{service}};
if (playerModel.isAvailable()) {
    auto state{Viper::CommitState::make(Viper::CommitId::Invalid(), definitions, {})};
    auto mutableState{Viper::CommitMutableState::make(state)};
    std::string nickname{"the shadow man"};

    // Execution runs on the SERVER — mutations land in the
    // CLIENT-LOCAL `mutableState` via the Remote-Local protocol below.
    auto key{playerModel.create(mutableState, nickname, service::demo::Level::Beginner)};
}

service->close();

The static TypeScript path

The TypeScript client, service/typescript/src/client.ts, does the same over @digitalsubstrate/dsviper, with the function pools of the PoolRemote feature reached through the package’s pools entry and the attachment pools of AttachmentPoolRemote through attachment_pools:

import { Level } from "../generated/dist/demo/index.js";
import { tools } from "../generated/dist/pools.js";
import { player_model } from "../generated/dist/attachment_pools.js";

const toolsRemote = new tools.Remote(serviceRemote);
if (toolsRemote.isAvailable()) {
    console.log(`add(32,10) -> ${toolsRemote.add(32n, 10n)}`);
}

const playerModel = new player_model.Remote(serviceRemote);
if (playerModel.isAvailable()) {
    console.log(`key is ${playerModel.create(mutating, nickname, Level.BEGINNER)}`);
}

See TypeScript, Pools.

The Kibo-generated parts are the per-pool Remote classes (service::tools::Remote, service.tools.remote.Remote, tools.Remote) and the marshalling for each method. All three languages get them from the same DSM, so the same pool has the same functions on every side.

Stateful calls execute remotely, mutate locally

Stateful pool calls (AttachmentFunctionPool) use the Remote-Local Protocol — the business logic runs on the server, but every read and mutation lands in the client’s local CommitAttachmentMutating via RPC callbacks. The roles invert during execution, and persistence is triggered by the client alone, never by the server. That isolation is what makes the design safe at the state-ownership level.

When to use a service

Add a service tier when one of these is true:

  • The business surface should be reachable from outside its own process — multiple clients, scripting from another tool, integration with an unrelated language.

  • Heavy computation must run on a powerful server, not on a resource-constrained client.

  • The same business logic must back several user-facing surfaces (desktop app, web app, CLI tool) without duplication.

A service is not useful when:

  • The work is single-user and single-process — calling pools in-process is sufficient and faster.

  • The exchange is purely about transporting an opaque database artefact across clients with no domain-specific operations to expose. For that, dedicated database-transport tools (e.g. the commit_database_server for commit databases) are simpler.

Security

Viper services share the network surface and security posture of all Viper RPC endpoints — trusted-network assumption, no built-in auth or transport encryption. See Security posture.

References

Source code

Location

What

devkit-codegen-test/service/

Canonical worked example — DSM, kibo.toml, server, three clients, pool implementations

devkit-codegen-test/service/cpp/src/ServiceServer.cpp

Server binary

devkit-codegen-test/service/cpp/src/ToolsPoolBridges.cpp, PlayerModelPoolBridges.cpp

The pools’ functions, implemented by hand

devkit-codegen-test/service/cpp/src/ServiceClient.cpp

C++ client using generated typed proxies

devkit-codegen-test/service/python/src/client.py

Python client using generated typed proxies

devkit-codegen-test/service/typescript/src/client.ts

TypeScript client using generated typed proxies

dsviper-tools/service_client.py

Five-line connection scaffold for the universal dynamic client

dsviper API

  • dsviper.ServiceRemote, dsviper.ServiceRemoteFunction, dsviper.ServiceRemoteAttachmentFunction, dsviper.ServiceRemoteAttachmentFunctionPoolFunction — the client-side surface (see Remote Services).

DSM language