RealtimeHub

MPO Version: 1.3.0

Defines a bidirectional realtime communication hub powered by Socket.IO. Each hub provides room-based messaging with built-in message types (text, image, video, audio, document, sticker, contact, location, system) and optional custom message types for app-specific structured data. Messages are always persisted to an auto-generated DataObject. The hub auto-bridges CRUD events from the room, membership, and message DataObjects via Kafka, and provides standard events (typing, read receipts, presence) as toggles. Hubs are mounted as Socket.IO namespaces and expose auto-generated REST endpoints.

interface RealtimeHub = {
  hubBasics : HubBasics;
  roomSettings : HubRoomSettings;
  hubRoles : HubRole[];
  messageSettings : HubMessageSettings;
  eventSettings : HubEventSettings;
  historySettings : HubHistorySettings;
  guardrails : HubGuardrails;
  hubLogic : HubLogic;
}

HubBasics

MPO Version: 1.3.0

Core identity of the realtime hub. The name is used as the Socket.IO namespace path /hub/{name}, REST endpoint prefix /{name}, and code identifier.

interface HubBasics = {
  name : String;
  description : Text;
}

HubRoomSettings

MPO Version: 1.3.0

Configures how rooms are managed and who can join them. Every hub requires a roomDataObject -- an existing DataObject that represents rooms. Authorization uses a layered flow: (1) roomEligibility checks if the room supports real-time features, (2) absoluteRoles bypass all checks, (3) checkRoles gates access to specific user roles, (4) checkScript applies a custom condition, (5) authSources and authScripts (OR-logic) determine the user's hub role. The first matching authSource/authScript wins (ordered highest-privilege first).

interface HubRoomSettings = {
  roomDataObject : LocalDataObjectName;
  roomEligibility : MScript;
  absoluteRoles : String[];
  checkRoles : String[];
  checkScript : MScript;
  authSources : HubAuthSource[];
  authScripts : HubAuthScript[];
}

HubAuthSource

MPO Version: 1.3.0

A DataObject-based authorization source for hub room access. Queries Elasticsearch for a record in the specified DataObject where userField matches the authenticated user and roomField matches the target room. If a record is found (and the optional condition passes), the user is granted the specified hubRole. Sources are evaluated top-to-bottom; the first match wins.

interface HubAuthSource = {
  name : String;
  sourceObject : DataObjectName;
  userField : PropRefer;
  roomField : PropRefer;
  condition : MScript;
  hubRole : String;
}

HubAuthScript

MPO Version: 1.3.0

An MScript-based authorization source for hub room access. The script is evaluated with user (session data) and room (room record from Elasticsearch) as context variables. Scripts can call library functions for complex logic. If the script returns true, the user is granted the specified hubRole. Scripts are evaluated after authSources, top-to-bottom; the first match wins.

interface HubAuthScript = {
  name : String;
  script : MScript;
  hubRole : String;
}

HubRole

MPO Version: 1.3.0

Defines a named permission set for hub users. Each role controls what actions a user can perform within a room. Roles are assigned by authSources, authScripts, or absoluteRoles. A built-in system role (all permissions true) is automatically used for absoluteRoles users. When globalModeration or the role's moderated flag is true, messages require moderator approval before broadcast.

interface HubRole = {
  name : String;
  canRead : Boolean;
  canSend : Boolean;
  allowedMessageTypes : String;
  moderated : Boolean;
  canModerate : Boolean;
  canDeleteAny : Boolean;
  canManageRoom : Boolean;
}

HubMessageSettings

MPO Version: 1.3.0

Controls message structure and persistence. Every hub auto-generates a Message DataObject with system fields (id, roomId, senderId, timestamp), a messageType enum column, and a content JSONB column. Designers select which built-in message types to support (text, image, video, etc.) and can define custom message types with app-specific field schemas. Cross-cutting features (reply threading, reactions, forwarded flag) are toggleable across all message types.

interface HubMessageSettings = {
  dataObjectName : String;
  messageTypes : HubMessageType[];
  enableReplyTo : Boolean;
  enableReaction : Boolean;
  enableForwarded : Boolean;
  customMessageTypes : HubCustomMessageType[];
}

HubMessageType

Built-in message content types for hub messages. Each type defines a known content schema stored in the message's content JSONB column.

const HubMessageType = {
  text: "text",
  image: "image",
  video: "video",
  audio: "audio",
  document: "document",
  sticker: "sticker",
  contact: "contact",
  location: "location",
  system: "system",
};

HubCustomMessageType

MPO Version: 1.3.0

Defines a custom (app-specific) message type for the hub. Custom message types extend the built-in types with designer-defined names and field schemas. Each custom type adds its name to the messageType enum in the generated DataObject. The content JSONB column stores the fields defined here, validated at runtime. Examples: chessMove with from/to/piece fields, nudge with animation field, bid with amount/currency fields.

interface HubCustomMessageType = {
  name : String;
  description : String;
  fields : HubCustomField[];
}

HubCustomField

MPO Version: 1.3.0

Defines a single field in a custom message type's content schema. Fields are stored inside the message's content JSONB column and validated before persistence and broadcast. For Enum types, provide comma-separated allowed values in enumValues.

interface HubCustomField = {
  name : String;
  fieldType : HubCustomFieldType;
  required : Boolean;
  description : String;
  enumValues : String;
  defaultValue : String;
}

HubCustomFieldType

Data types for fields in custom message type definitions.

const HubCustomFieldType = {
  String: "String",
  Text: "Text",
  Integer: "Integer",
  Decimal: "Decimal",
  Boolean: "Boolean",
  ID: "ID",
  DateTime: "DateTime",
  Enum: "Enum",
  JSON: "JSON",
};

HubEventSettings

MPO Version: 1.3.0

Configures standard events, auto-bridged DataObject events, custom events, and external Kafka events. Standard events (typing, recording, read receipts, delivery receipts, presence) are toggleable -- the framework generates the socket handlers and payload validation. Auto-bridge automatically listens to CRUD events from the room, membership, and message DataObjects and broadcasts them to hub rooms. Custom events and Kafka events remain for app-specific signals and external sources.

interface HubEventSettings = {
  enableTypingIndicator : Boolean;
  enableRecordingIndicator : Boolean;
  enableReadReceipts : Boolean;
  enableDeliveryReceipts : Boolean;
  enablePresence : Boolean;
  autoBridgeDataEvents : Boolean;
  customEvents : HubCustomEvent[];
  kafkaEvents : HubKafkaEvent[];
}

HubCustomEvent

MPO Version: 1.3.0

Defines a custom event that clients or the server can emit within the hub. Custom events go beyond standard messages -- they carry typed payloads for signals like typing indicators, read receipts, game actions, or system notifications. Ephemeral events are broadcast but not persisted.

interface HubCustomEvent = {
  name : String;
  description : String;
  ephemeral : Boolean;
  direction : HubEventDirection;
}

HubEventDirection

Defines the direction of a custom hub event.

const HubEventDirection = {
  clientToRoom: "clientToRoom",
  serverToClient: "serverToClient",
  serverToRoom: "serverToRoom",
};

HubKafkaEvent

MPO Version: 1.3.0

Bridges a Kafka topic message into the hub as a room-scoped event. When a matching message arrives on the configured Kafka topic, the filterExpression is evaluated. If it passes, the targetRoomExpression extracts the room ID, and the event is broadcast to all clients in that room. Use for backend-driven updates like participant changes, status transitions, or external system notifications.

interface HubKafkaEvent = {
  name : String;
  description : String;
  topic : String;
  filterExpression : MScript;
  targetRoomExpression : MScript;
}

HubHistorySettings

MPO Version: 1.3.0

Controls whether message history is sent to clients when they join a room. When enabled, the server queries the message DataObject for the most recent messages and emits them as a hub:history event immediately after join confirmation.

interface HubHistorySettings = {
  historyEnabled : Boolean;
  historyLimit : Integer;
}

HubGuardrails

MPO Version: 1.3.0

Safety limits, rate controls, moderation settings, and caching for the hub. Prevents resource exhaustion, abuse, and oversized payloads. All values have sensible defaults but should be tuned for production use cases.

interface HubGuardrails = {
  maxUsersPerRoom : Integer;
  maxRoomsPerUser : Integer;
  messageRateLimit : Integer;
  maxMessageSize : Integer;
  connectionTimeout : Integer;
  authCacheTTL : Integer;
  globalModeration : Boolean;
  defaultSilenced : Boolean;
}

HubLogic

MPO Version: 1.3.0

Server-side logic hooks for the hub. Allows intercepting custom message types with MScript before broadcast, fetching room state on join or on demand, and running scheduled actions on an interval. MScript hooks can call service library functions, Redis, DB, Business APIs, or external services -- the hub just provides the hook points and acts on the return values. Intercepted messages are queued per-room to prevent race conditions.

interface HubLogic = {
  stateScript : MScript;
  messageHandlers : HubMessageHandler[];
  scheduledActions : HubScheduledAction[];
}

HubMessageHandler

MPO Version: 1.3.0

Intercepts a specific custom message type and routes it through an MScript before broadcast. The script receives the message, sender session, room record, and service library, and returns an object controlling accept/reject, broadcast targets, message modifications, persistence, and server-generated messages. Use for game moves, bids, collaborative edits, or any message that needs server-side validation or state management.

interface HubMessageHandler = {
  messageType : String;
  script : MScript;
}

The returned object from the handler script has a shape like:

{
  accept: boolean;
  rejectReason?: string;
  broadcast?: boolean;
  broadcastTo?: "all" | "others" | "sender" | string[];
  modifiedContent?: Record<string, unknown>;
  persist?: boolean;
  serverMessages?: Array<{
    type: string;
    content: Record<string, unknown>;
    to: "all" | "others" | "sender" | string[];
    persist?: boolean;
  }>;
}

HubScheduledAction

MPO Version: 1.3.0

A recurring action that runs on an interval for each active room. The script is called every intervalMs milliseconds and can return serverMessages to broadcast. The interval starts when the first user joins the room and stops when the last user disconnects, unless keepAlive is true. Use for game world ticks, NPC movement, countdown timers, or periodic state sync.

interface HubScheduledAction = {
  name : String;
  intervalMs : Integer;
  keepAlive : Boolean;
  script : MScript;
}

The script return value has a shape like:

{
  serverMessages?: Array<{
    type: string;
    content: Record<string, unknown>;
    to: "all" | "others" | "sender" | string[];
    persist?: boolean;
  }>;
}