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 markedmutablein the DSM takes aCommitAttachmentMutatingand may write; a function without it (hasPlayerabove) takes anAttachmentGettingand only reads.AttachmentGettingandCommitAttachmentMutatingare 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()andservice::player_model::pool()are generated by thePoolandAttachmentPoolfeatures, one namespace per pool: each returns theViper::FunctionPool(orViper::AttachmentFunctionPool) that registers the functions the pool declares. The functions themselves are declared in that namespace and implemented by hand —cpp/src/ToolsPoolBridges.cppandcpp/src/PlayerModelPoolBridges.cpphold 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 |
|---|---|
|
Canonical worked example — DSM, |
|
Server binary |
|
The pools’ functions, implemented by hand |
|
C++ client using generated typed proxies |
|
Python client using generated typed proxies |
|
TypeScript client using generated typed proxies |
|
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¶
function_poolandattachment_function_poolkeywords — see Concepts and Hierarchies.