morph::wire::Envelope Struct Reference

JSON wire envelope used between any client and RemoteServer. More...

#include <wire.hpp>

Public Attributes
std::string	kind
	Discriminator — see class docstring for valid values.
uint64_t	callId = 0
	Correlation id for matching async replies to their requests.
std::string	typeId
	Model type id for register.
std::string	contextKey
	Stable identity of the model instance being registered or attached to (e.g. an account id). Empty means "no identity" — the server-side holder gets no action log attached even if a LogProvider is configured. Carried on register and attach; ignored on every other kind.
std::string	primary
	Primary key of the instance being registered or attached to.
bool	shared = false
	Whether a register should join the shared instance directory.
uint64_t	modelId = 0
	Existing model instance id for deregister, execute, ok(register).
std::string	modelType
	Model type id for execute (routing key in ActionDispatcher).
std::string	actionType
	Action type id for execute (the second routing key).
std::string	body
	Serialized JSON of the action payload (execute) or of the deserializable result (ok).
std::string	message
	Free-text error message on err. Empty on success.
::morph::session::Context	session
	Session context for authorization and routing. Populated on execute; ignored on every other kind.
std::uint32_t	protocolVersion = 0
	Protocol version the sender speaks.
std::uint64_t	cancelCallId = 0
	The callId of the execute a "cancel" asks the server to stop.

Detailed Description

JSON wire envelope used between any client and RemoteServer.

Supersedes the legacy pipe-delimited protocol: a single struct carries all request and reply variants, with the kind field acting as a discriminator. Empty/zero fields are tolerated — callers populate only what their kind needs.

Discriminator values

• "register" — client requests model creation. Uses typeId, and optionally contextKey (the new instance's stable identity, e.g. an account id — see ServerConfig::logProvider). With shared set, additionally uses primary and becomes a register-or-attach against the shared directory.
• "attach" — client re-points at a different primary of typeId, releasing modelId if non-zero. Replies ok with the target instance's id in modelId.
• "assign" — client files live modelId under primary of typeId.
• "instances" — client asks for the live shared primary keys of typeId. Replies ok with a JSON array of key strings in body.
• "schemas" — client asks for the action descriptions of typeId. Replies ok with a {actionType: schema} JSON object in body — see "Serving action schemas" in docs/spec/core/wire.md.
• "deregister" — client destroys an instance. Uses modelId.
• "execute" — client dispatches an action. Uses callId, modelId, modelType, actionType, body, and optionally session.
• "ok" — server success reply. Uses callId if present and carries the serialized result in body. For register replies, modelId carries the new id.
• "err" — server failure reply. Uses callId if present and message.
• "hello" — client opens protocol-version negotiation, once per connection before any other kind. Uses protocolVersion; see makeHello() and interpretHelloReply(). A peer predating negotiation answers err "unknown envelope kind: hello", which is how a legacy server is detected.
• "event" — server-initiated notification, sent unprompted on a connection that negotiated events. callId is 0; body is an EventBody. A client routes it by kind before reply matching; see makeEvent().
• "cancel" — client asks the server to stop one of its own in-flight execute calls. Uses cancelCallId (the execute's callId) and session; its own callId correlates the ok reply, which is the same whatever became of the call. Sent only to a server whose hello reply advertised kCapabilityCancel; see makeCancel().

Definition at line 91 of file wire.hpp.

Member Data Documentation

kind

std::string morph::wire::Envelope::kind

Discriminator — see class docstring for valid values.

Definition at line 93 of file wire.hpp.

callId

uint64_t morph::wire::Envelope::callId = 0

Correlation id for matching async replies to their requests.

Definition at line 96 of file wire.hpp.

typeId

std::string morph::wire::Envelope::typeId

Model type id for register.

Definition at line 99 of file wire.hpp.

contextKey

std::string morph::wire::Envelope::contextKey

Stable identity of the model instance being registered or attached to (e.g. an account id). Empty means "no identity" — the server-side holder gets no action log attached even if a LogProvider is configured. Carried on register and attach; ignored on every other kind.

Definition at line 106 of file wire.hpp.

primary

std::string morph::wire::Envelope::primary

Primary key of the instance being registered or attached to.

Carried on register (when shared is set) and on attach, always as the key's canonical string encoding (morph::model::keyToString) whatever its C++ type, so the server's directory needs one map type rather than one per key type. Empty means "no primary" — the instance is anonymous and cannot be shared. Ignored on every other kind.

Distinct from contextKey, which continues to mean only "entity key for the action log". A keyed model will normally set both to the same value, but conflating the fields would change behaviour for callers already setting contextKey for journal purposes.

Definition at line 120 of file wire.hpp.

shared

bool morph::wire::Envelope::shared = false

Whether a register should join the shared instance directory.

true makes the request a register-or-attach: the server returns the existing instance for (typeId, primary) if one is live, otherwise creates it and enters it in the directory. false (the default, and the value every pre-existing client sends) is today's behaviour exactly — a private instance, invisible to the directory.

Definition at line 129 of file wire.hpp.

modelId

uint64_t morph::wire::Envelope::modelId = 0

Existing model instance id for deregister, execute, ok(register).

Definition at line 132 of file wire.hpp.

modelType

std::string morph::wire::Envelope::modelType

Model type id for execute (routing key in ActionDispatcher).

Definition at line 135 of file wire.hpp.

actionType

std::string morph::wire::Envelope::actionType

Action type id for execute (the second routing key).

Definition at line 138 of file wire.hpp.

body

std::string morph::wire::Envelope::body

Serialized JSON of the action payload (execute) or of the deserializable result (ok).

Definition at line 142 of file wire.hpp.

message

std::string morph::wire::Envelope::message

Free-text error message on err. Empty on success.

Definition at line 145 of file wire.hpp.

session

::morph::session::Context morph::wire::Envelope::session

Session context for authorization and routing. Populated on execute; ignored on every other kind.

Definition at line 149 of file wire.hpp.

protocolVersion

std::uint32_t morph::wire::Envelope::protocolVersion = 0

Protocol version the sender speaks.

0 means "unspecified / legacy peer" — the value on every envelope an old encoder (unaware of this field) produces, and the value an old decoder (unaware of this field) leaves untouched when it receives one from a newer peer (ignored via decode's error_on_unknown_keys = false). Populated by makeHello() on "hello"; not otherwise inspected by other kinds today.

Definition at line 159 of file wire.hpp.

cancelCallId

std::uint64_t morph::wire::Envelope::cancelCallId = 0

The callId of the execute a "cancel" asks the server to stop.

Carried in its own field rather than in callId because a cancel is a request with a reply of its own: were the target's id in callId, the server's ok to the cancel would be matched by the client against the still-pending execute and settle it with an empty result. 0 names no call. Ignored on every other kind.

Definition at line 168 of file wire.hpp.

---

The documentation for this struct was generated from the following file:

• morph/core/wire.hpp