vix.cpp v2.8.3

vix.cpp v2.8.3 is the first stable and supported release of the v2.8 line.

versions v2.8.0, v2.8.1, and v2.8.2 were published while release and distribution problems were still being resolved. they remain in the project history for traceability, but they should not be used as production releases. developers using an earlier v2.8 build should move to v2.8.3.

the main change in v2.8 is the introduction of vix::realtime, a transport-independent runtime for authoritative stateful applications. it provides the application model needed for rooms, commands, events, logical sessions, snapshots, replay, reconnection, presence, and persistence without tying those concepts to a particular network transport.

this release is the point where that architecture is delivered as the supported v2.8 release.

release focus

realtime applications often begin with a websocket connection and quickly grow beyond it. once several clients share state, the difficult part is no longer opening a socket. the application needs one authoritative version of that state, a defined order for mutations, a way to recover after a process restart, and enough session information to reconnect a client without losing consistency.

vix::realtime moves those responsibilities into a dedicated runtime.

applications define their room state and command handling logic. vix manages the execution boundary around that logic: commands are serialized, accepted state changes become authoritative events, events can be persisted, snapshots can be created, rooms can be restored, and logical sessions can continue across network reconnections.

the runtime is deliberately separate from websocket. a websocket adapter is available, but rooms, sessions, replay, persistence, and state recovery belong to the realtime model itself rather than to one transport implementation.

authoritative rooms

a realtime room owns one authoritative application state.

instead of allowing multiple connections to mutate shared state independently, commands enter one serialized execution path. this gives the room a clear ordering model and prevents concurrent command handling from producing conflicting versions of the same state.

applications remain responsible for the state they want to model. a room can represent a game world, collaborative document, chat room, shared dashboard, presence space, or another application-specific domain. vix provides the lifecycle and consistency machinery around that state without defining what the state itself must contain.

rooms can be opened and closed explicitly, created from application-defined factories, joined by logical sessions, and configured with limits for command queues, memberships, snapshots, and inactive-room cleanup.

commands, events, and room versions

state changes begin as commands.

a command carries the information required to identify the room, session, request, expected room version, payload, metadata, and creation time. the room handler decides whether that command is valid and which events should result from it.

accepted events receive authoritative identifiers and room versions before they are persisted and applied to state. this ordering is important because persistence, replay, recovery, and client synchronization all need to refer to the same sequence of state transitions.

events can be delivered to the entire room, only to the sending session, to every session except the sender, or to a selected set of sessions. audience selection is part of the realtime model, while the actual delivery remains the responsibility of the active transport adapter.

this keeps application state deterministic without forcing every event to be broadcast in the same way.

snapshots and deterministic recovery

long-lived rooms cannot depend only on in-memory state.

vix::realtime can create snapshots automatically after a configured number of events, explicitly when requested, or when a room is closed. a configurable number of recent snapshots can be retained so the persistence layer does not have to keep every historical state representation.

recovery follows one consistent sequence. vix loads the latest available snapshot, restores its state and schema information, replays events created after that snapshot, restores the current room version and event position, then allows new commands to continue from the recovered point.

if no snapshot exists, the runtime can rebuild the room from its persisted event history.

the important property is that recovery uses the same events that originally changed the room. restoring the same persisted history therefore produces the same authoritative state and room version, and reopening a room does not duplicate events that were already stored.

logical sessions

network connections are temporary. application sessions usually are not.

the realtime runtime therefore separates a logical session from the socket or transport connection currently carrying its messages. a session has a stable identifier, identity and metadata, room memberships, connection attachment state, a resume token, and acknowledgement positions for the rooms it has joined.

a temporary connection loss does not immediately destroy that logical state.

when the client reconnects, the runtime can validate the resume token, attach the new connection, restore memberships, and determine which room events the client has not yet acknowledged.

this model avoids making tcp or websocket connection lifetime the source of truth for application identity.

reconnection and replay

a resumed session can continue from its last acknowledged event position.

if the missing range is small enough, vix replays the events that were persisted while the client was disconnected. a session can maintain a different acknowledgement position for each room, which matters when one client participates in several independent realtime spaces.

when the client is too far behind for bounded replay, the runtime can fall back to a snapshot. the client receives the latest available room snapshot, the events created after that snapshot, and the final replay position.

this keeps reconnection practical even for rooms with long histories. a stale client does not need to replay every event that has ever existed before it can become current again.

presence

presence is modeled separately from room state.

the initial runtime includes local presence tracking for sessions inside rooms. presence records can carry identity, node ownership, connection information, metadata, heartbeat timestamps, and lifecycle state.

a session can be present, temporarily detached, or explicitly left. expiration and stale-record cleanup make it possible to distinguish a short connection interruption from a session that should no longer appear in the room.

keeping presence separate from application state also avoids forcing every room implementation to rebuild the same connection-awareness logic.

room management

roommanager coordinates the runtime-level relationship between rooms, sessions, stores, presence, factories, and command routing.

it can register room factories, open and locate rooms, create and find logical sessions, join and leave memberships, attach and detach transport connections, route commands, enforce configured limits, clean up inactive rooms, and participate in controlled runtime shutdown.

the module also introduces room directory and ownership abstractions. an active room can be associated with the node responsible for its authoritative execution.

the first release still focuses on the local runtime, but separating room identity from node ownership provides the boundary needed for future multi-process and distributed routing.

persistence stores

persistence is exposed through interfaces rather than being embedded directly in room implementations.

the realtime runtime defines stores for room events, room snapshots, and presence records. the initial implementation includes in-memory event and snapshot stores, along with local in-memory presence storage.

an application can therefore begin with a completely local runtime and later replace the persistence layer without changing its room state or command handlers.

optional postgresql event and snapshot stores are also available. postgresql support is independent from the transport layer, so persistent rooms do not require websocket and websocket applications do not require postgresql.

websocket adapter

vix::realtime can be used without websocket support.

for applications that do use vix::websocket, v2.8 adds an adapter between the transport and the realtime runtime. the adapter handles the connection-facing parts of the protocol, including session opening and resumption, room joins and leaves, command forwarding, event delivery, acknowledgements, protocol errors, and connection backpressure.

the separation is intentional. websocket answers how messages move between a client and server. the realtime runtime answers how shared application state is ordered, persisted, recovered, and associated with logical sessions.

keeping those responsibilities distinct allows another transport to reuse the same room and session model later.

realtime protocol

the module includes a versioned protocol envelope for communication between realtime clients and servers.

the protocol covers session opening and resumption, room membership, commands, command acceptance and rejection, events, snapshots, acknowledgements, replay completion, presence updates, ping and pong messages, protocol errors, and server draining notifications.

protocol parsing includes version checks and structured errors so malformed or incompatible messages can be rejected at the boundary before they reach application room logic.

applications that do not need the provided transport protocol can still use the underlying room runtime independently.

public api

the stable module entry point is:

#include <vix/realtime.hpp>

advanced apis remain available through module-specific headers:

#include <vix/realtime/...>

the public cmake targets are:

vix_realtime
vix::realtime

the realtime module also has standalone package metadata under:

vix/realtime

its first standalone module version is 0.1.0.

this keeps the realtime runtime usable both as part of the complete vix sdk and as a module with its own package boundary.

examples

four examples are included to exercise the runtime through complete application flows rather than isolated api calls.

the counter example demonstrates commands, deterministic events, automatic snapshots, state restoration, and continued room versions after recovery.

the shared-room example uses multiple sessions against one authoritative state and shows room membership together with room-wide event delivery.

the chat example adds persistent messages, room history, snapshots, and restoration.

the reconnect example exercises acknowledgements, temporary disconnection, resume-token validation, missing-event replay, snapshot fallback, and restoration of the final authoritative state.

these examples are useful because they test the boundaries between features. reconnection depends on sessions, acknowledgements, persistence, replay, and room state all agreeing on the same history.

release stabilization

the first three v2.8 tags should be treated as superseded release attempts.

v2.8.0 introduced the new realtime architecture, but the release line still had distribution and packaging problems. v2.8.1 and v2.8.2 continued the stabilization work, including fixes to standalone module dependencies, but they were not accepted as stable releases.

for that reason, the supported v2.8 line begins with v2.8.3.

the older tags remain available because removing them would erase useful release history and make existing references harder to understand. their presence should not be interpreted as a recommendation to install them.

if a machine or ci environment is pinned to v2.8.0, v2.8.1, or v2.8.2, update that pin to v2.8.3.

validation

the realtime module has dedicated strict ci coverage across gcc and clang, debug and release configurations, websocket-enabled and transport-independent builds, examples, sanitizers, compiler warnings, static analysis, memory checks, postgresql store compilation, package metadata, and cmake package contracts.

the test suite covers identifiers, commands, events, protocol parsing and round trips, room state, persistence stores, snapshot policy, sessions, presence, room lifecycle, command backpressure, ownership, room management, the websocket adapter, resume tokens, reconnection replay, snapshot fallback, and complete realtime session flows.

the four runtime examples were also executed as part of validation:

counter
shared_room
chat
reconnect

the recovery tests verify monotonic room versions and event identifiers, event persistence, automatic snapshots, restoration after snapshots, full replay when no snapshot exists, continued execution after recovery, replay from acknowledged positions, and snapshot fallback for stale clients.

the release was also checked through the standalone module and packaged-runtime paths so that the supported tag represents more than a successful source-tree build.

compatibility

vix::realtime is a new module and does not replace the existing websocket runtime.

applications that only need websocket messaging can continue using vix::websocket directly. applications that need authoritative state, session recovery, replay, or persistent rooms can place the realtime runtime above the transport layer and use the websocket adapter when appropriate.

postgresql support remains optional. in-memory stores are available for local applications, tests, and simpler deployments.

the public realtime umbrella header and cmake targets provide the stable entry points. lower-level headers remain available for applications that need more direct control over stores, protocols, sessions, or room management.

upgrade notes

do not use v2.8.0, v2.8.1, or v2.8.2 for a new installation.

existing users of one of those versions should move to v2.8.3 and verify the installed version with:

vix --version

projects using the realtime module should also rebuild against the v2.8.3 sdk or package set rather than carrying binaries or generated build state from one of the superseded releases.

release summary

vix.cpp v2.8.3 establishes the supported foundation for stateful realtime applications in vix.

the new vix::realtime module gives shared application state an explicit execution and recovery model: rooms serialize commands, accepted changes become deterministic events, snapshots bound recovery cost, logical sessions survive temporary connection loss, acknowledgements define replay positions, and persistence remains replaceable behind store interfaces.

websocket is available as an adapter rather than being the architecture itself, and postgresql can be added when persistent room history is required.

most importantly for the v2.8 release line, v2.8.3 is the version developers should actually install. v2.8.0, v2.8.1, and v2.8.2 remain in history as superseded release attempts; v2.8.3 is the first stable and supported v2.8 release.