API Reference

This page summarizes the public C++ API of Vix Realtime.

For normal use, include the umbrella header:

#include <vix/realtime.hpp>

and link:

vix::realtime

The public API is in:

namespace vix::realtime

Protocol types use:

namespace vix::realtime::protocol

Detailed behavior is covered by the dedicated Realtime guides. This page is intended as a compact reference.

Version

Current module version:

0.1.0

Compile-time values:

vix::realtime::version_major
vix::realtime::version_minor
vix::realtime::version_patch
vix::realtime::version

Compatibility check:

vix::realtime::version_compatible(0, 1);

Version macros:

VIX_REALTIME_VERSION_MAJOR
VIX_REALTIME_VERSION_MINOR
VIX_REALTIME_VERSION_PATCH
VIX_REALTIME_VERSION_STRING

Common types

Realtime defines these common aliases:

Type	Meaning
JsonObject	Realtime JSON object
VersionValue	Numeric room-version value
EventIdValue	Numeric event identifier value
SystemClock	System clock
SteadyClock	Steady clock
Timestamp	System-clock timestamp
SteadyTimestamp	Steady-clock timestamp
Identity	Application identity string
ConnectionId	Transport connection identifier
CorrelationId	Operation correlation identifier
RequestId	Request identifier
ResumeToken	Session resume credential
SchemaVersion	Application state schema version

Identifiers

RoomId

Identifies one logical room.

vix::realtime::RoomId roomId{"room-1"};

Important members:

value()
view()
empty()
size()
is_valid()
validate()

Maximum length:

128

RoomId supports equality, ordering, and std::hash.

SessionId

Identifies one logical session.

vix::realtime::SessionId sessionId{
    "session-1"};

Important members:

value()
view()
empty()
size()
is_valid()
validate()

Maximum length:

128

SessionId supports equality, ordering, and std::hash.

NodeId

Identifies one Realtime runtime node.

vix::realtime::NodeId nodeId{"node-1"};

Important members:

value()
view()
empty()
size()
is_valid()
validate()

Maximum length:

128

NodeId supports equality, ordering, and std::hash.

RoomVersion

Represents the logical version of authoritative room state.

vix::realtime::RoomVersion version{3};

Important members:

value()
is_initial()
next()
increment()

Initial value:

0

EventId

Represents one persistent position in a room event stream.

vix::realtime::EventId eventId{3};

Important members:

value()
empty()
next()
increment()

Empty value:

0

Persistent event identifiers normally begin at 1.

Errors

ErrorCode

Realtime error codes include:

None
InvalidConfiguration
MissingDependency

RoomNotFound
RoomAlreadyExists
RoomFull
RoomLimitReached
RoomNotReady
RoomClosed

CommandQueueFull
InvalidCommand
CommandRejected
CommandTimeout
Unauthorized

SessionNotFound
SessionExpired
InvalidResumeToken
ConnectionNotAttached
MembershipNotFound
AlreadyJoined

InvalidProtocolMessage
UnsupportedProtocolVersion
PayloadTooLarge

EventStoreFailure
SnapshotStoreFailure
CorruptedState
EventApplyFailure

ReplayUnavailable
ReplayLimitExceeded

TransportFailure
Cancelled
Timeout
InternalError

SessionAlreadyConnected
SessionNotDetached

Convert a code to its stable textual form with:

vix::realtime::to_string(code);

Error

Realtime exceptions use:

vix::realtime::Error

Important members:

code()
what()

Example:

catch (const vix::realtime::Error &error)
{
    auto code = error.code();
}

See Errors.

Configuration

Config

Runtime configuration:

vix::realtime::Config config;

Public fields:

maxActiveRooms
maxSessions
maxSessionsPerRoom
maxRoomsPerSession
maxPendingCommandsPerRoom

maxReplayEvents
maxReplayBytes
maxResumeRooms

snapshotEveryEvents
snapshotsToKeep

roomIdleTimeout
sessionResumeWindow
presenceTimeout
replayTimeout

snapshotOnRoomClose
restoreRoomsOnOpen
enableSessionResume
enablePresence

Important operations:

Config::from_core()
validate()

See Configuration.

Server

ServerStatus

Created
Running
Stopping
Stopped
Failed

Server

Main public Realtime facade.

vix::realtime::Server server{
    vix::realtime::NodeId{"node-1"}};

Lifecycle:

start()
stop()
status()
running()
stopped()

Room operations:

register_factory()
unregister_factory()

open_room()
close_room()
find_room()

Session operations:

create_session()
find_session()
connect()
disconnect()
close_session()

Membership:

join_room()
leave_room()

Commands:

execute()
enqueue()
process_next()

Messaging:

send()

Cleanup:

prune_expired_sessions()
prune_stale_presence()

Runtime access:

manager()
node_id()
config()

Pointer alias:

vix::realtime::ServerPtr

See Server.

Rooms

RoomStatus

Created
Opening
Open
Closing
Closed
Failed

Room

Represents one authoritative room runtime.

Lifecycle:

open()
close()
status()
is_open()
is_closed()
failed()

Commands:

execute()
command()
process_command()
execute_command()

enqueue()
process_next()
pending_command_count()

Membership:

join()
join_session()
add_session()
add_member()
leave()

has_session()
sessions()
session_count()
member_count()
empty()

State and position:

state()
serialize_state()
version()
last_event_id()

Events:

broadcast()
broadcast_event()
publish_event()
emit()

Snapshots:

snapshot()

Other state:

id()
type()
config()
last_activity_at()

owner_node_id()
set_owner_node_id()
clear_owner_node_id()

metadata()
set_metadata()

Pointer aliases:

vix::realtime::RoomPtr
vix::realtime::WeakRoomPtr

See Rooms.

Room state

RoomState

Application-defined authoritative room state.

Required interface:

class State : public vix::realtime::RoomState
{
public:
    vix::realtime::SchemaVersion
    schema_version() const noexcept override;

    void apply(
        const vix::realtime::RoomEvent &) override;

    vix::realtime::JsonObject
    serialize() const override;

    void restore(
        const vix::realtime::JsonObject &,
        vix::realtime::SchemaVersion) override;

    std::unique_ptr<vix::realtime::RoomState>
    clone() const override;
};

Pointer alias:

vix::realtime::RoomStatePtr

See Room State.

Room context

RoomContext

Immutable information supplied to application room handlers.

Important accessors:

room_id()
room_version()
last_event_id()

next_room_version()
next_event_id()

session_id()
request_id()
correlation_id()
node_id()

now()
metadata()

is_valid()
validate()

Room handlers

RoomHandler

Application behavior for one room type.

Required command callback:

handle_command()

Lifecycle callbacks:

on_open()
on_join()
on_leave()
on_close()

Lifecycle callbacks have default implementations that return an accepted result.

Pointer alias:

vix::realtime::RoomHandlerPtr

See Room Handlers.

Room factories

RoomComponents

Contains:

state
handler

Operations:

is_valid()
validate()

RoomFactory

Creates state and handlers for one application room type.

Required interface:

room_type()
create_state()
create_handler()

Convenience operation:

create()

Validation helper:

is_valid_type()

Maximum room type length:

128

Pointer alias:

vix::realtime::RoomFactoryPtr

Commands

RoomCommand

Represents client intent.

Basic construction:

vix::realtime::RoomCommand command{
    roomId,
    sessionId,
    "counter.increment"};

Accessors:

room_id()
session_id()
type()
payload()

request_id()
correlation_id()
expected_version()

created_at()
metadata()

Modifiers:

set_correlation_id()
set_expected_version()
clear_expected_version()
set_created_at()
set_metadata()

Validation:

is_valid()
validate()
is_valid_type()

Maximum command type length:

128

See Commands and Results.

Command results

CommandStatus

Accepted
Rejected
Ignored

CommandResult

Factory methods:

accepted()
rejected()
ignored()

Inspection:

status()

is_accepted()
is_rejected()
is_ignored()

has_events()
event_count()
events()

error_code()
message()
metadata()

Modification:

add_event()
set_message()
set_metadata()

Validation:

is_valid()
validate()

See Commands and Results.

Command queue status

CommandQueueStatus

Success
Full
Empty
Closed
Timeout

Convert to text with:

vix::realtime::to_string(status);

Events

EventAudience

Room
Sender
Others
Session
Internal

See Events for recipient semantics.

RoomEvent

Represents one authoritative room fact.

Accessors:

event_id()
room_id()
room_version()

type()
payload()
audience()

target_session()
source_session()

request_id()
correlation_id()

schema_version()
created_at()
metadata()

Modifiers:

set_event_id()
set_room_version()

set_audience()

set_target_session()
clear_target_session()

set_source_session()
clear_source_session()

set_request_id()
set_correlation_id()

set_schema_version()
set_created_at()
set_metadata()

Validation:

is_valid()
validate()
is_valid_type()

Maximum event type length:

128

See Events.

Room snapshots

RoomSnapshot

Represents one serialized room-state checkpoint.

Accessors:

room_id()
room_version()
last_event_id()

state()
schema_version()
created_at()

checksum()
metadata()

Modifiers:

set_room_version()
set_last_event_id()
set_schema_version()
set_created_at()

set_checksum()
clear_checksum()

set_metadata()

Validation:

is_valid()
validate()

See Snapshots.

Event stores

EventStore

Abstract authoritative event persistence interface.

Required operations:

append()
append_batch()
load_after()
latest_event_id()
count()
clear_room()

Pointer alias:

vix::realtime::EventStorePtr

MemoryEventStore

Thread-safe process-memory implementation of EventStore.

Additional operations:

clear()
room_count()

See Event Store.

Snapshot stores

SnapshotStore

Abstract snapshot persistence interface.

Required operations:

save()
load_latest()
load_at_or_before()
load_recent()
count()
prune()
clear_room()

Pointer alias:

vix::realtime::SnapshotStorePtr

MemorySnapshotStore

Thread-safe process-memory implementation.

Additional operations:

clear()
room_count()

See Snapshots.

Sessions

SessionStatus

Connected
Detached
Closed

Compatibility alias:

vix::realtime::SessionState

Session

Represents one logical client.

Identity:

id()
identity()

Lifecycle:

status()
connected()
detached()
closed()
close()

Connections:

attach()
detach()
connection()
connection_id()

Membership:

join_room()
leave_room()
has_room()
rooms()
room_count()

Recovery positions:

acknowledge()
last_event_id()

Resume state:

resume_token()
set_resume_token()
clear_resume_token()
can_resume()

Activity:

created_at()
last_seen_at()
detached_at()
touch()

Messaging:

send()

Metadata:

metadata()
set_metadata()

Pointer aliases:

vix::realtime::SessionPtr
vix::realtime::WeakSessionPtr

See Sessions.

Connections

Connection

Transport-independent client connection interface.

Required operations:

id()
is_open()
send()
close()

Optional metadata:

metadata()

Pointer aliases:

vix::realtime::ConnectionPtr
vix::realtime::WeakConnectionPtr

See Connections.

Session resume

SessionResumeResult

Contains:

session
replacedConnection
resumeToken
tokenRotated

It can be checked with:

success()

SessionResume

Session reconnection and recovery service.

Token operations:

issue()
rotate()
revoke()
matches()

Eligibility:

can_resume()

Resume:

resume()

Runtime information:

resume_window()
manager()

Pointer alias:

vix::realtime::SessionResumePtr

See Session Resume.

Presence

PresenceStatus

Present
Detached
Left

Presence

Represents one logical session's presence in one room.

Identity:

room_id()
session_id()
identity()

Placement:

node_id()
connection_id()

Status:

status()
logically_present()
connected()
detached()
left()

Timestamps:

joined_at()
last_seen_at()
detached_at()
left_at()

Lifecycle modifiers include operations for:

touching activity
marking present
marking detached
marking left
updating node information
updating connection information

Metadata:

metadata()
set_metadata()

Validation:

is_valid()
validate()

See Presence.

Presence stores

PresenceStore

Abstract presence persistence interface.

Operations include:

upsert()
find()

touch()
mark_present()
mark_detached()
mark_left()

list_room()
list_session()

erase()
prune_stale()

count_room()
count()

clear_room()
clear_session()

Pointer alias:

vix::realtime::PresenceStorePtr

LocalPresenceStore

Thread-safe process-local implementation.

Additional helpers include:

prune_expired()
clear()
room_count()

See Presence.

Distributed presence

DistributedPresenceStatus

Healthy
Degraded
Unavailable

DistributedPresenceNode

Contains:

nodeId
lastSeen
local
metadata

It also provides stale-node evaluation.

DistributedPresence

Extends PresenceStore with multi-node coordination operations.

Important operations:

local_node_id()
heartbeat()

find_node()
nodes()
active_nodes()
node_active()

prune_stale_nodes()
clear_node()

distributed_status()
ping()

Pointer alias:

vix::realtime::DistributedPresencePtr

Realtime currently defines this interface but does not provide a concrete distributed backend.

See Distributed Presence.

Room ownership

RoomOwnerGeneration

using RoomOwnerGeneration = std::uint64_t;

RoomOwnerStatus

Active
Releasing
Released

RoomOwner

Represents an ownership claim and exposes information including:

room_id()
node_id()
generation()
status()

acquired_at()
renewed_at()
expires_at()
released_at()

has_lease()
expired()
active()

It also provides ownership lifecycle operations used by room coordination.

Metadata:

metadata()
set_metadata()

Validation:

is_valid()
validate()

See Room Ownership.

RoomDirectory

Process-local room ownership directory.

Ownership operations include:

acquire()
renew()
make_permanent()

begin_release()
release()
transfer()

resolve()
inspect()

owns()
matches()

latest_generation()
active_owners()
owned_by()

prune_expired()

The directory also keeps local room registrations used by RoomManager.

See Room Ownership.

Room manager

RoomManager

Process-local coordinator for rooms, sessions, membership, presence, and ownership.

Factories:

register_factory()
unregister_factory()
find_factory()
has_factory()
factory_types()

Rooms:

open_room()
open()
get_or_open_room()

close_room()

find_room()
require_room()
has_room()

room_ids()
room_count()

Sessions:

create_session()

find_session()
require_session()
has_session()

session_ids()
session_count()

close_session()

Connections:

attach_connection()
detach_connection()

Membership:

join_room()
leave_room()

Commands:

execute()
enqueue()
process_next()

Presence:

find_presence()
room_presence()

Cleanup:

cleanup()
cleanup_inactive()
shutdown()

Dependencies:

event_store()
snapshot_store()
presence_store()
room_directory()

Runtime information:

node_id()
config()

Pointer alias:

vix::realtime::RoomManagerPtr

See Room Manager.

Protocol

Protocol types are in:

vix::realtime::protocol

protocol::Version

Fields:

major
minor

Check compatibility with:

protocol::is_supported(version);

Current protocol:

1.0

protocol::MessageKind

Request
Response
Event
Error
Snapshot
Control

Compatibility alias:

Command = Request

Helpers:

is_valid()
to_string()
parse_message_kind()

protocol::Envelope

Core accessors:

version()
kind()
type()
payload()

message_id()
request_id()
correlation_id()

room_id()
session_id()

room_version()
event_id()
schema_version()

created_at()
metadata()

The class also provides setters for the optional identifiers and metadata.

Validation:

is_valid()
validate()
is_valid_type()

Protocol conversion helpers include:

from_command()
from_event()
from_snapshot()
make_error()

Serialization:

serialize()
parse()

See Protocol.

Transport

Callback aliases:

TransportOpenHandler
TransportEnvelopeHandler
TransportCloseHandler
TransportErrorHandler

TransportHandlers

Callbacks:

onOpen
onEnvelope
onClose
onError

Helper:

empty()

Transport

Abstract network adapter interface.

Required operations:

set_handlers()
handlers()

attach()
detach()
attached()

connection_count()

Pointer alias:

vix::realtime::TransportPtr

See Transport.

WebSocket adapter

Available when:

VIX_REALTIME_WITH_WEBSOCKET

is enabled.

WebSocketAdapterOptions

Fields:

maxMessageSize
closeOnProtocolError
connectionIdPrefix

Validation:

validate()

Defaults:

maxMessageSize       = 64 KiB
closeOnProtocolError = true
connectionIdPrefix   = "ws"

WebSocketAdapter

Implements Transport.

Transport operations:

set_handlers()
handlers()

attach()
detach()
attached()

connection_count()

Connection access:

find_connection()
connections()

Adapter information:

websocket_server()
options()

Pointer alias:

vix::realtime::WebSocketAdapterPtr

See WebSocket Integration.

PostgreSQL event store

PostgreSQL support is compiled when:

VIX_REALTIME_WITH_POSTGRES

is enabled.

PostgresEventStoreOptions

Fields:

connectionString
schema
table
createSchemaIfMissing
createTableIfMissing
reconnect

Defaults:

schema                = public
table                 = vix_realtime_events
createSchemaIfMissing = false
createTableIfMissing  = true
reconnect             = true

Validation:

validate()

PostgresEventStore

Implements EventStore.

Operations:

append()
append_batch()
load_after()
latest_event_id()
count()
clear_room()

PostgreSQL-specific operations:

ping()
options()
compiled_with_postgres()

Pointer alias:

vix::realtime::PostgresEventStorePtr

See PostgreSQL.

PostgreSQL snapshot store

PostgresSnapshotStoreOptions

Fields:

connectionString
schema
table
createSchemaIfMissing
createTableIfMissing
reconnect

Defaults:

schema                = public
table                 = vix_realtime_snapshots
createSchemaIfMissing = false
createTableIfMissing  = true
reconnect             = true

Validation:

validate()

PostgresSnapshotStore

Implements SnapshotStore.

Operations:

save()
load_latest()
load_at_or_before()
load_recent()
count()
prune()
clear_room()

PostgreSQL-specific operations:

ping()
options()
compiled_with_postgres()

Pointer alias:

vix::realtime::PostgresSnapshotStorePtr

See PostgreSQL.

Metrics

MetricsSnapshot

Contains point-in-time counters, gauges, and duration aggregates for:

rooms
sessions
connections
commands
events
snapshots
replay
resume
presence
transport
protocol errors
runtime errors

Convenience calculations include:

average_command_duration()
maximum_command_duration()

average_snapshot_duration()
maximum_snapshot_duration()

average_replay_duration()
maximum_replay_duration()

event_delivery_success_rate()
resume_success_rate()

has_errors()

Metrics

Thread-safe explicit metrics collector.

Gauge operations cover:

active rooms
active sessions
attached connections
queued commands
active presence

Recording operations cover:

room lifecycle
session lifecycle
connection lifecycle
commands
event persistence
event dispatch
snapshots
replay
session resume
presence
transport traffic
protocol errors
runtime errors

Read current values with:

snapshot()

Reset the collector with:

reset()

Pointer alias:

vix::realtime::MetricsPtr

See Metrics.

Health

HealthStatus

Healthy
Degraded
Unhealthy
Stopped

HealthOptions

Fields:

requireSnapshotStore
requirePresenceStoreWhenEnabled
degradeOnDetachedSessions

maxQueuedCommands
recordedErrorTolerance
protocolErrorTolerance

HealthReport

Contains:

status
checkedAt
nodeId
serverStatus

room counts
ownership count
queued command count

session counts
presence count

store availability
presence availability
room-directory availability
metrics availability

metrics
issues

Helpers:

healthy()
operational()
has_issues()

HealthMonitor

Create from a server:

vix::realtime::HealthMonitor monitor{
    server};

Operations:

check()
server()
metrics()
options()

Pointer alias:

vix::realtime::HealthMonitorPtr

See Health.

Public headers

The public Realtime headers are:

vix/realtime.hpp

vix/realtime/api.hpp
vix/realtime/realtime.hpp
vix/realtime/version.hpp
vix/realtime/types.hpp
vix/realtime/errors.hpp
vix/realtime/config.hpp

vix/realtime/room_id.hpp
vix/realtime/session_id.hpp
vix/realtime/node_id.hpp
vix/realtime/room_version.hpp
vix/realtime/event_id.hpp

vix/realtime/room_command.hpp
vix/realtime/command_result.hpp
vix/realtime/command_queue_status.hpp
vix/realtime/room_event.hpp
vix/realtime/event_audience.hpp
vix/realtime/room_snapshot.hpp

vix/realtime/room_state.hpp
vix/realtime/room_context.hpp
vix/realtime/room_handler.hpp
vix/realtime/room_factory.hpp

vix/realtime/room.hpp
vix/realtime/room_manager.hpp
vix/realtime/server.hpp

vix/realtime/connection.hpp
vix/realtime/session.hpp
vix/realtime/session_resume.hpp

vix/realtime/presence.hpp
vix/realtime/presence_store.hpp
vix/realtime/local_presence_store.hpp
vix/realtime/distributed_presence.hpp

vix/realtime/event_store.hpp
vix/realtime/memory_event_store.hpp
vix/realtime/snapshot_store.hpp
vix/realtime/memory_snapshot_store.hpp

vix/realtime/room_owner.hpp
vix/realtime/room_directory.hpp

vix/realtime/protocol.hpp
vix/realtime/transport.hpp
vix/realtime/websocket_adapter.hpp

vix/realtime/postgres_event_store.hpp
vix/realtime/postgres_snapshot_store.hpp

vix/realtime/metrics.hpp
vix/realtime/health.hpp

Headers under:

vix/realtime/internal/

are implementation details and are not part of the stable public API.

Pointer aliases

Common ownership aliases include:

RoomPtr
WeakRoomPtr

SessionPtr
WeakSessionPtr

ConnectionPtr
WeakConnectionPtr

RoomManagerPtr
ServerPtr

RoomStatePtr
RoomHandlerPtr
RoomFactoryPtr

EventStorePtr
SnapshotStorePtr
PresenceStorePtr
DistributedPresencePtr

TransportPtr
WebSocketAdapterPtr

SessionResumePtr

PostgresEventStorePtr
PostgresSnapshotStorePtr

MetricsPtr
HealthMonitorPtr

Use the public aliases where they make ownership intent clearer.

Main API relationships

The primary public types fit together as:

Server
  |
  v
RoomManager
  |
  +---- RoomFactory
  |       |
  |       +---- RoomState
  |       +---- RoomHandler
  |
  +---- Room
  |       |
  |       +---- RoomCommand
  |       +---- CommandResult
  |       +---- RoomEvent
  |
  +---- Session
  |       |
  |       +---- Connection
  |
  +---- EventStore
  +---- SnapshotStore
  +---- PresenceStore
  +---- RoomDirectory

Transport integration remains separate:

Transport
   |
   v
Connection + protocol::Envelope
   |
   v
application integration
   |
   v
Server

The stable application model is:

RoomCommand
    |
    v
RoomHandler
    |
    v
CommandResult
    |
    v
RoomEvent
    |
    v
EventStore
    |
    v
RoomState

For a first application, start with Quick Start. For the behavioral model behind these types, see Core Concepts.