Skip to content

Framework Overview

Foundation topic index · Spec index · Previous: 02. Framework Messaging Glossary · Next: 04. Interaction Model

Defines what the Framework does as an upper layer, what the basic concepts that identify mesh and channel scopes refer to, how a message target is selected, and which execution owner receives it.

1. What the Framework Does

The ZLink Framework is the upper layer that connects a typed message handler, mesh and channel messaging, Spot, Actor with per-ID state and a mailbox, connection sessions, PUB/SUB-style broadcast, and the location runtime to an application host's lifecycle and DI.

  • The C++, .NET, JVM, and Node.js Frameworks each implement the service runtime independently in their own language. This runtime uses only the installed public raw socket API of that language's binding.
  • What the languages share is the public contract, the versioned protocol schema, and verification fixtures; they do not share a common native runtime or a service C ABI. This is because the observable contract must stay the same even when each language implementation has a different binary.
  • Java and Kotlin share one JVM runtime.

2. MeshName, ChannelName, and RouteMesh

RouteMesh is the physical connection scope of the MeshNodes that share the same MeshName — the name that identifies the physical mesh and RID namespace within which they can message each other.

One MeshNode has one routing ID and one ROUTER endpoint.

A MeshNode that provides a channel handler participates as a Server in one or more immutable ChannelNames — names that identify the Channel scopes to which messages are sent.

A call-only MeshNode, or one dedicated to Node direct — sending by designating a MeshName and target RID together — can operate without any ChannelName membership.

MeshName and ChannelName play different roles.

Name Meaning
MeshName The physical mesh and RID namespace that can message each other
ChannelName A process-local logical address that selects a RouteMesh or ClientServer send path
  • One process can have multiple MeshNodes with different MeshNames. Each mesh is independent and provides no automatic relay.
  • Adding a RouteMesh ChannelName does not add a socket or endpoint. This is because a ChannelName is only a process-local logical address and does not create a physical connection.
  • Within the same process, one ChannelName maps to only one RouteMesh or ClientServer topology. In a call role, it points to one send path of that topology.

3. Message Target Selection

Messaging on a MeshNode is distinguished by how the target is selected.

  • Node direct designates one RID within the same MeshName.
  • A channel send/request finds a process-local send path by ChannelName, and selects one ready target among that RouteMesh's members or that ClientServer's servers.
  • Spot Logical Multicast targets the remote MeshNodes of a ChannelName and their node-local Spot subscriptions.
  • A Spot or Actor message designates either a Spot ID — the global logical address that identifies a Spot — or an Actor ID. The Framework uses the value recorded in the Location Store to look up which node currently holds that ID, then places the message in the mailbox of the object on that node. The value that records "who currently holds it" is called authority.
  • Spot/Actor create and get-or-create are explicit manager operations the application calls directly. The Framework selects a node for creation based on the object role, remaining capacity, stable type, and per-node placement weight, then returns an immutable ref once the object is ready to receive messages.

Selection and submit are one operation. An application does not receive a peer list or a selected RID and then repeat separate send calls.

4. Logical Multicast and Classic Fanout

Spot Logical Multicast delivers an event to a logical Spot whose location can change, such as a room, stage, or zone. The sending MeshNode sends one routed message per remote MeshNode of the target channel, and the receiving MeshNode checks its own node's subscriptions.

%%{init: {'sequence': {'actorFontSize': '18px', 'messageFontSize': '18px', 'noteFontSize': '18px', 'boxMargin': 8, 'width': 140}, 'themeVariables': {'fontSize': '18px'}}}%%
sequenceDiagram
    participant Src as Sending MeshNode
    participant A as Remote MeshNode A
    participant B as Remote MeshNode B

    Note over Src: Submits independently to the local Spot queue as well
    Src->>A: One routed message (ROUTER send)
    A->>A: Checks node-local Spot subscriptions
    Note over A: When multiple Spots match,<br/>a shared storage reference is enqueued in each queue
    Src->>B: One routed message (ROUTER send)
    B->>B: Checks node-local Spot subscriptions
    Note over Src,B: Even if the send to B fails,<br/>the submit already accepted by A is not canceled
  • When multiple Spots match on the same node, a reference to the immutable message storage is shared and enqueued in each Spot's queue. This avoids duplicating the message body once per Spot.
  • The HWM, send timeout, and backpressure of a remote send follow the ordinary ROUTER rules as-is. This is because Logical Multicast does not have a separate flow-control path.
  • A later target's failure does not cancel a submit already accepted by an earlier target. This is because each target is submitted independently.

Classic fanout is an independent PUB/SUB capability that sends an event to a subscriber that is connected and has finished subscription setup.

  • A publisher using automatic discovery publishes its actual endpoint to a dedicated location descriptor, and an automatic subscriber connects to every live publisher of the same ChannelName.
  • A publisher and subscriber using only manual endpoints can be configured without a location store. A host that does not need a MeshNode or Spot can also use this method.
  • Classic fanout does not guarantee storage or replay. It delivers only events published after connection and subscription setup is complete.

5. Execution Owner

The Framework delivers a message to the execution unit that actually owns the state.

The execution objects below are distinct from the MeshNode Owner in Location Store authority. Handler turn and execution gate §7 owns the per-execution-object FIFO scope.

Execution object Responsibility
Node RID direct and ChannelName handlers, node-initiated completions
Spot Spot direct (send/request delivery using one global Spot ID), Logical Multicast subscriptions, timers, and Spot state. An Instance Spot uses only direct messaging and timers, not Actor membership or Logical Multicast subscriptions.
Actor Actor direct messages, Actor lifecycle, and the per-Actor mailbox
STREAM session — the server-side execution unit maintained from acceptance of one STREAM connection until that connection closes Connection lifecycle, packet dispatch, and Actor-binding ingress
  • An application is not required to redistribute a Spot or Actor message from a Node handler. This is because the Framework service runtime drains the per-owner bounded mailbox and connects it directly to the registered handler's execution context.
  • Transport readiness and the service protocol frame are not exposed to an application callback. This is so an application can continue processing using only the per-owner execution state.

6. Connection Management

Automatic discovery uses a location store's descriptor and lease.

  • RouteMesh looks up a MeshNode descriptor with the same MeshName, and a ClientServer client looks up a dedicated server descriptor with the same ChannelName. Neither descriptor can substitute for the other.
  • A host that uses an Object Client/Server role or distributed discovery explicitly registers the official Redis location store instance.

A manual peer is a connection intent the application provides, either as an endpoint or as an expected RID plus endpoint.

  • A manual peer also passes the same MeshName, RID, ChannelName, generation, and security admission checks as an automatic-discovery peer. Being manual does not change the message path or handler meaning.

A ClientServer Channel is a separate service connection where a client initiates a business call and a server provides the handler and request reply. It is used for a one-way service boundary that does not need Node direct, Spot, Actor, or Logical Multicast. The detailed roles and discovery contract are owned by ClientServer Channel.

7. What the Framework Hides

The Framework internally manages transport address selection, peer reconnect, multipart framing, packet codec, reply correlation, and the backpressure queue. An application handler uses a typed payload and context, and does not configure raw socket wiring itself.

Authentication, quota, WAF, public API versioning, and billing for an external edge gateway are not within this framework's contract scope.

8. Verification Requirements

Using only the public messaging API (node direct, channel send/request, Spot Logical Multicast, Spot/Actor message, classic fanout publish/subscribe, manual peer registration), verify the following.

Target Selection and Submit

  • Target selection and submit finish in one call — the caller does not receive a peer list or a selected RID and then repeat separate send calls.
  • In Spot Logical Multicast, even if the send to a later target fails, the submit for an earlier target that was already accepted is not canceled.

Classic Fanout

  • A classic fanout subscriber receives only events published after connection and subscription setup is complete — an event published before then is not redelivered.

Connection Admission

  • A manual peer connects only after passing the same MeshName, RID, ChannelName, generation, and security admission checks as an automatic-discovery peer.

Foundation topic index · Spec index · Previous: 02. Framework Messaging Glossary · Next: 04. Interaction Model