Files

narawat 8d31c5829b update

2026-03-13 17:37:21 +07:00

32 KiB

Raw Blame History

Specification: NATSBridge

Version: 1.0.0
Date: 2026-03-13
Status: Active
Ground Truth: src/NATSBridge.jl
Specification Format: JSON Schema + AsyncAPI

Executive Summary

This document defines the technical contract for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between Julia, JavaScript, Python, and MicroPython applications using NATS as the message bus.

This specification serves as the single source of truth for:

Inputs: What data structures are accepted by smartsend()
Outputs: What data structures are returned by smartreceive()
Data Shapes: Exact field names, types, and constraints
Error Codes: Standardized error responses for failure scenarios

Specification Versioning

Component	Version	Notes
Specification	1.0.0	Initial release
Protocol	v1	Message envelope protocol version

Message Envelope Schema

Envelope Structure (JSON)

{
  "correlation_id": "string (UUID)",
  "msg_id": "string (UUID)",
  "timestamp": "string (ISO 8601 UTC)",
  "send_to": "string",
  "msg_purpose": "string",
  "sender_name": "string",
  "sender_id": "string (UUID)",
  "receiver_name": "string",
  "receiver_id": "string (UUID)",
  "reply_to": "string",
  "reply_to_msg_id": "string",
  "broker_url": "string",
  "metadata": "object",
  "payloads": [
    {
      "id": "string (UUID)",
      "dataname": "string",
      "payload_type": "string",
      "transport": "string",
      "encoding": "string",
      "size": "integer",
      "data": "string or URL",
      "metadata": "object"
    }
  ]
}

Field Definitions

Field	Type	Required	Validation	Description
`correlation_id`	`string`	Yes	UUID v4 format	Track message flow across distributed systems
`msg_id`	`string`	Yes	UUID v4 format	Unique identifier for this specific message
`timestamp`	`string`	Yes	ISO 8601 UTC	Message publication timestamp (e.g., `2026-03-13T07:02:50.443Z`)
`send_to`	`string`	Yes	Non-empty string	NATS subject/topic to publish the message to
`msg_purpose`	`string`	Yes	Enum	Purpose of the message (see `msg_purpose` enum)
`sender_name`	`string`	Yes	Non-empty string	Name of the sender application
`sender_id`	`string`	Yes	UUID v4 format	Unique identifier for the sender
`receiver_name`	`string`	Yes	Any string	Name of the receiver (empty = broadcast)
`receiver_id`	`string`	Yes	Any string	UUID of the receiver (empty = broadcast)
`reply_to`	`string`	Yes	Any string	Topic where receiver should reply (empty = no reply expected)
`reply_to_msg_id`	`string`	Yes	Any string	Message ID this message is replying to
`broker_url`	`string`	Yes	Valid URL	NATS broker URL
`metadata`	`object`	No	Any JSON object	Message-level metadata
`payloads`	`array`	Yes	Non-empty array	List of payload objects

Payload Schema

Payload Structure (JSON)

{
  "id": "string (UUID)",
  "dataname": "string",
  "payload_type": "string",
  "transport": "string",
  "encoding": "string",
  "size": "integer",
  "data": "string or URL",
  "metadata": "object"
}

Payload Field Definitions

Field	Type	Required	Validation	Description
`id`	`string`	Yes	UUID v4 format	Unique identifier for this payload
`dataname`	`string`	Yes	Non-empty string	Name of the payload (e.g., `login_image`, `user_data`)
`payload_type`	`string`	Yes	Enum	Type of payload (see `payload_type` enum)
`transport`	`string`	Yes	Enum	Transport method: `direct` or `link`
`encoding`	`string`	Yes	Enum	Encoding method (see `encoding` enum)
`size`	`integer`	Yes	Positive integer	Size of the payload in bytes
`data`	`string` or `URL`	Yes	Base64 string or URL	Payload data (base64 for direct, URL for link)
`metadata`	`object`	No	Any JSON object	Payload-level metadata

Payload Format

Tuple Format for `smartsend()`

The smartsend() function accepts data as an array of tuples with the format:

("data_name", data, "data_type")

Position	Type	Description	Example
1	`string`	Data name - identifier for the payload	`"msg"`, `"login_image"`, `"user_data"`
2	`any`	Actual data - content to be serialized	`"Hello"`, `{"key": "value"}`, `DataFrame(...)`
3	`string`	Data type - must be in `payload_type` enum	`"text"`, `"dictionary"`, `"arrowtable"`

Single Payload Example

# Julia
smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])

# Python
await smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])

// JavaScript
await smartsend("/chat/user/v1/message", [["msg", "Hello World", "text"]]);

Multiple Payloads Example

# Julia - Mixed text and binary data
data = [
    ("msg", "Hello", "text"),
    ("img", binary_data, "image")
]
smartsend("/agent/v1/process", data)

# Python - Mixed types
data = [
    ("msg", "Hello", "text"),
    ("img", binary_data, "image")
]
await smartsend("/agent/v1/process", data)

Data Type Mapping

Platform	Input Type	Data Type String
All	`String`	`"text"`
All	`Dict`/`Object`	`"dictionary"`
Desktop	`DataFrame`	`"arrowtable"` or `"jsontable"`
All	`Array` of objects	`"jsontable"`
All	`Uint8Array`/`Buffer`/`bytes`	`"binary"`
Desktop	`Arrow.Table`	`"arrowtable"`
All	Image/Audio/Video binary	`"image"`, `"audio"`, `"video"`

Enumerations

`msg_purpose` Enum

Value	Description
`ACK`	Acknowledgment of successful message processing
`NACK`	Negative acknowledgment of message processing failure
`updateStatus`	Status update message
`shutdown`	Graceful shutdown request
`chat`	Chat/message payload
`command`	Command payload
`event`	Event payload

`payload_type` Enum

Value	Description	Supported Platforms	Encoding Options
`text`	Plain text string	All	`base64`
`dictionary`	JSON object/dictionary	All	`base64`, `json`
`arrowtable`	Apache Arrow IPC table	Desktop (Julia/JS/Python)	`base64`, `arrow-ipc`
`jsontable`	JSON array of objects	All	`base64`, `json`
`image`	Binary image data	All	`base64`
`audio`	Binary audio data	All	`base64`
`video`	Binary video data	All	`base64`
`binary`	Generic binary data	All	`base64`

`transport` Enum

Value	Description	Data Format	Use Case
`direct`	Payload sent directly via NATS	Base64-encoded string	Payloads < size_threshold
`link`	Payload uploaded to file server	HTTP URL	Payloads ≥ size_threshold

`encoding` Enum

Value	Description	Payload Types
`none`	No additional encoding	Link transport URLs
`base64`	Base64 encoding	Text, binary, image, audio, video
`json`	JSON encoding	Dictionary, jsontable
`arrow-ipc`	Apache Arrow IPC format	Arrowtable

Transport Protocols

Direct Transport Protocol

When transport = "direct", the data field contains a Base64-encoded string of the serialized payload.

Flow:

Serialize payload according to payload_type
Encode serialized bytes as Base64
Include Base64 string in data field

Example:

{
  "transport": "direct",
  "encoding": "base64",
  "size": 11,
  "data": "SGVsbG8gV29ybGQ="
}

Link Transport Protocol

When transport = "link", the data field contains a URL pointing to the uploaded payload.

Flow:

Serialize payload according to payload_type
Upload to HTTP file server (e.g., Plik)
Include returned URL in data field

Example:

{
  "transport": "link",
  "encoding": "none",
  "size": 1000000,
  "data": "http://localhost:8080/file/3F62E/4AgGT/data.zip"
}

Size Thresholds

Desktop Platforms (Julia/JS/Python)

Platform	Size Threshold	Notes
Desktop	500,000 bytes (0.5MB)	Default threshold

MicroPython Platform

Platform	Size Threshold	Maximum Payload	Notes
MicroPython	100,000 bytes (100KB)	50,000 bytes	Hard limit due to memory constraints

NATS Subject Convention

Subject Naming Pattern

<scope>/<service>/<version>/<operation>

Examples:

/agent/wine/api/v1/prompt - AI agent prompt endpoint
/chat/user/v1/message - User chat message
/system/worker/v1/status - Worker status update

Subject Wildcards

Wildcard	Description	Example
`*`	Single-level wildcard	`/chat/user/v1/*` matches `/chat/user/v1/message`
`>`	Multi-level wildcard	`/chat/user/v1/>` matches all `/chat/user/v1/*` subjects

Error Handling

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object"
  }
}

Error Codes

Code	HTTP Status	Description	Recovery
`INVALID_ENVELOPE`	400	Message envelope validation failed	Fix envelope structure
`INVALID_PAYLOAD_TYPE`	400	Unsupported payload type	Use supported payload_type
`INVALID_TRANSPORT`	400	Unsupported transport type	Use `direct` or `link`
`UPLOAD_FAILED`	500	File server upload failed	Retry or use direct transport
`DOWNLOAD_FAILED`	503	File server download failed	Retry with exponential backoff
`NATS_CONNECTION_FAILED`	503	NATS connection failed	Check NATS server availability
`DESERIALIZATION_ERROR`	500	Payload deserialization failed	Check payload_type matches data
`SIZE_EXCEEDED`	413	Payload exceeds maximum size	Split payload or use link transport

Exception Handling

Scenario	Handler	Retry Policy
File server unavailable	Retry up to 5 times	Exponential backoff (100ms → 5000ms)
NATS publish failure	Connection auto-reconnect	TCP-level reconnection
Deserialization error	Log correlation ID and throw	No retry (data corruption)
Memory overflow (MicroPython)	Reject payloads >50KB	No retry (client-side check)

Serialization Rules

Text Serialization

Platform	Input Type	Serialization	Encoding
All	`String`	UTF-8 bytes	Base64

Dictionary Serialization

Platform	Input Type	Serialization	Encoding
All	`Object`/`Dict`	JSON string	Base64 or direct JSON

Arrow Table Serialization

Platform	Input Type	Serialization	Encoding
Desktop	`DataFrame`	Arrow IPC stream	Base64 or arrow-ipc
Desktop	`Arrow.Table`	Arrow IPC stream	Base64 or arrow-ipc
MicroPython	❌	Not supported	N/A

JSON Table Serialization

Platform	Input Type	Serialization	Encoding
All	`Vector{Dict}`/`Array<Object>`	JSON array	Base64 or direct JSON
Desktop	`pandas.DataFrame`	JSON array	Base64 or direct JSON

Binary Serialization

Platform	Input Type	Serialization	Encoding
All	`Uint8Array`/`Buffer`/`bytes`	Raw bytes	Base64

API Contract

`smartsend` Function Signature

Julia

function smartsend(
    subject::String,
    data::AbstractArray{Tuple{String, Any, String}};
    broker_url::String = "nats://localhost:4222",
    fileserver_url::String = "http://localhost:8080",
    fileserver_upload_handler::Function = plik_oneshot_upload,
    size_threshold::Int = 500_000,
    correlation_id::String = string(uuid4()),
    msg_purpose::String = "chat",
    sender_name::String = "NATSBridge",
    receiver_name::String = "",
    receiver_id::String = "",
    reply_to::String = "",
    reply_to_msg_id::String = "",
    is_publish::Bool = true,
    NATS_connection::Union{NATS.Connection, Nothing} = nothing,
    msg_id::String = string(uuid4()),
    sender_id::String = string(uuid4())
)::Tuple{msg_envelope_v1, String}

Python

async def smartsend(
    subject: str,
    data: List[Tuple[str, Any, str]],
    broker_url: str = "nats://localhost:4222",
    fileserver_url: str = "http://localhost:8080",
    fileserver_upload_handler: Callable = plik_oneshot_upload,
    size_threshold: int = 500_000,
    correlation_id: str = None,
    msg_purpose: str = "chat",
    sender_name: str = "NATSBridge",
    receiver_name: str = "",
    receiver_id: str = "",
    reply_to: str = "",
    reply_to_msg_id: str = "",
    is_publish: bool = True,
    nats_connection: Any = None,
    msg_id: str = None,
    sender_id: str = None
) -> Tuple[Dict, str]:

JavaScript (Node.js)

async function smartsend(
    subject: string,
    data: Array<[string, any, string]>,
    options?: {
        broker_url?: string;
        fileserver_url?: string;
        fileserver_upload_handler?: Function;
        size_threshold?: number;
        correlation_id?: string;
        msg_purpose?: string;
        sender_name?: string;
        receiver_name?: string;
        receiver_id?: string;
        reply_to?: string;
        reply_to_msg_id?: string;
        is_publish?: boolean;
        nats_connection?: NATS.Connection;
        msg_id?: string;
        sender_id?: string;
    }
): Promise<[Object, string]>;

JavaScript (Browser)

async function smartsend(
    subject: string,
    data: Array<[string, any, string]>,
    options?: {
        broker_url?: string;
        fileserver_url?: string;
        fileserver_upload_handler?: Function;
        size_threshold?: number;
        correlation_id?: string;
        msg_purpose?: string;
        sender_name?: string;
        receiver_name?: string;
        receiver_id?: string;
        reply_to?: string;
        reply_to_msg_id?: string;
        is_publish?: boolean;
        nats_connection?: NATS.Connection;
        msg_id?: string;
        sender_id?: string;
    }
): Promise<[Object, string]>;

MicroPython

def smartsend(
    subject: str,
    data: List[Tuple[str, Any, str]],
    **kwargs
) -> Tuple[Dict, str]:

`smartreceive` Function Signature

Julia

function smartreceive(
    msg::NATS.Msg;
    fileserver_download_handler::Function = _fetch_with_backoff,
    max_retries::Int = 5,
    base_delay::Int = 100,
    max_delay::Int = 5000
)::JSON.Object{String, Any}

Python

async def smartreceive(
    msg: Any,
    fileserver_download_handler: Callable = fetch_with_backoff,
    max_retries: int = 5,
    base_delay: int = 100,
    max_delay: int = 5000
) -> Dict[str, Any]:

JavaScript (Node.js)

async function smartreceive(
    msg: Object,
    options?: {
        fileserver_download_handler?: Function;
        max_retries?: number;
        base_delay?: number;
        max_delay?: number;
    }
): Promise<Object>;

JavaScript (Browser)

async function smartreceive(
    msg: Object,
    options?: {
        fileserver_download_handler?: Function;
        max_retries?: number;
        base_delay?: number;
        max_delay?: number;
    }
): Promise<Object>;

MicroPython

def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]:

File Server Interface

Upload Handler Contract

Function Signature:

function fileserver_upload_handler(
    file_server_url::String,
    dataname::String,
    data::Vector{UInt8}
)::Dict{String, Any}

Return Format:

{
  "status": 200,
  "uploadid": "string",
  "fileid": "string",
  "url": "string"
}

Required Keys:

Key	Type	Description
`status`	`integer`	HTTP response status code
`uploadid`	`string`	Upload session identifier
`fileid`	`string`	File identifier within session
`url`	`string`	Full download URL

Download Handler Contract

Function Signature:

function fileserver_download_handler(
    url::String,
    max_retries::Int,
    base_delay::Int,
    max_delay::Int,
    correlation_id::String
)::Vector{UInt8}

Retry Policy:

Initial delay: base_delay milliseconds
Maximum delay: max_delay milliseconds
Multiplier: 2x per retry
Maximum retries: max_retries

Platform-Specific Constraints

Desktop (Julia/JS/Python)

Feature	Status	Notes
Arrow IPC	✅ Supported	Requires Arrow.jl/pyarrow
JSON table	✅ Supported	Human-readable format
File server upload	✅ Supported	HTTP/HTTPS
File server download	✅ Supported	HTTP/HTTPS
Size threshold	500KB	Configurable

MicroPython

Feature	Status	Notes
Arrow IPC	❌ Not supported	Memory constraints
JSON table	⚠️ Limited	Only direct transport
File server upload	❌ Not implemented	Placeholder only
File server download	❌ Not implemented	Placeholder only
Size threshold	100KB	Hard limit enforced
Max payload	50KB	Hard limit enforced

Message Flow

Sending Flow

flowchart TD
    A[User calls smartsend subject data] --> B[Serialize payload according to payload_type]
    B --> C{Calculate serialized size}
    C -->|Size < Threshold| D[Direct Transport: Encode as Base64]
    C -->|Size >= Threshold| E[Link Transport: Upload to file server]
    D --> F[Build envelope with metadata]
    E --> F
    F --> G[Convert envelope to JSON string]
    G --> H[Publish to NATS subject]
    H --> I[Return envelope and JSON string to caller]
    
    style A fill:#f9f9f9,stroke:#333
    style I fill:#e0e7ff,stroke:#3b82f6
    style D fill:#d1fae5,stroke:#10b981
    style E fill:#fef3c7,stroke:#f59e0b

Receiving Flow

flowchart TD
    A[NATS message arrives] --> B[Parse JSON envelope]
    B --> C[For each payload: Check transport type]
    C -->|transport == direct| D[Direct Transport: Extract Base64]
    C -->|transport == link| E[Link Transport: Fetch from URL]
    D --> F[Decode Base64]
    E --> G[Fetch with exponential backoff]
    F --> H[Deserialize based on payload_type]
    G --> H
    H --> I[Build payloads array]
    I --> J[Replace payloads array with deserialized tuples]
    J --> K[Return envelope with processed payloads]
    
    style A fill:#f9f9f9,stroke:#333
    style K fill:#e0e7ff,stroke:#3b82f6
    style D fill:#d1fae5,stroke:#10b981
    style E fill:#fef3c7,stroke:#f59e0b

Validation Rules

Envelope Validation

Rule	Condition	Error Code
Required fields present	`correlation_id`, `msg_id`, `timestamp`, `send_to`, `payloads`	`INVALID_ENVELOPE`
Valid UUID format	`correlation_id`, `msg_id`, `sender_id`, `receiver_id`	`INVALID_ENVELOPE`
Valid timestamp format	ISO 8601 UTC	`INVALID_ENVELOPE`
Non-empty payloads array	`length(payloads) > 0`	`INVALID_ENVELOPE`

Payload Validation

Rule	Condition	Error Code
Valid payload_type	Must be in `payload_type` enum	`INVALID_PAYLOAD_TYPE`
Valid transport	Must be `direct` or `link`	`INVALID_TRANSPORT`
Valid encoding	Must match payload_type and transport	`INVALID_TRANSPORT`
Positive size	`size > 0`	`INVALID_PAYLOAD`
Valid Base64 for direct	`data` matches Base64 pattern	`DESERIALIZATION_ERROR`
Valid URL for link	`data` matches HTTP(S) URL pattern	`DOWNLOAD_FAILED`

Test Contracts

Unit Test Validation

Test	Input	Expected Output	Notes
Text round-trip	`("msg", "Hello", "text")`	`("msg", "Hello", "text")`	String serialization
Dictionary round-trip	`("data", {"key": "value"}, "dictionary")`	`("data", {"key": "value"}, "dictionary")`	JSON object round-trip
Arrow table round-trip	`("table", arrow_table_data, "arrowtable")`	`("table", arrow_table_data, "arrowtable")`	Arrow IPC round-trip
JSON table round-trip	`("table", [{"a":1},{"b":2}], "jsontable")`	`("table", [{"a":1},{"b":2}], "jsontable")`	JSON array of objects
Mixed payloads	`[("msg", "Hello", "text"), ("imgname", bytes, "binary")]`	`[("msg", "Hello", "text"), ("imgname", bytes, "binary")]`	Multiple payload types
Large payload	`("data", rand(10_000_000), "arrowtable")`	`("data", URL, "arrowtable")` with link transport	File server upload

Platform-Specific Notes:

Julia: Use Dict, Vector{Dict}, or convert DataFrame to dictionary for testing
Python: Use dict, list[dict], or convert pandas.DataFrame to dictionary for testing
JavaScript: Use plain objects {} and arrays []
MicroPython: Use plain dict and list (limited to JSON table and text types)

Integration Test Scenarios

Scenario	Platforms	Payloads	Size Mix	Transport	Expected Result
Single text (small)	All	`text`	Small	direct	Round-trip successful
Single dictionary (small)	All	`dictionary`	Small	direct	Round-trip successful
Single arrow table (small)	Julia/JS/Python	`arrowtable`	Small	direct	Arrow IPC round-trip
Single JSON table (small)	All	`jsontable`	Small	direct	Dictionary array round-trip
Single image (small)	All	`image`	Small	direct	Binary round-trip
Single audio (small)	All	`audio`	Small	direct	Binary round-trip
Single video (small)	All	`video`	Small	direct	Binary round-trip
Single binary (small)	All	`binary`	Small	direct	Binary round-trip
Single text (large)	All	`text`	Large	link	File server upload/download
Single JSON table (large)	All	`jsontable`	Large	link	File server upload/download
Single image (large)	All	`image`	Large	link	File server upload/download
Ultimate Test	Julia/JS/Python	`text` (small) + `dictionary` (small) + `arrowtable` (small) + `jsontable` (small) + `image` (small) + `audio` (small) + `video` (small) + `binary` (small) + `text` (large) + `dictionary` (large) + `arrowtable` (large) + `jsontable` (large) + `image` (large)	Mixed	direct/link	All payloads preserved with correct transport
Ultimate Test	Python	`text` (small) + `dictionary` (small) + `jsontable` (small) + `image` (small) + `audio` (small) + `video` (small) + `binary` (small) + `text` (large) + `dictionary` (large) + `jsontable` (large) + `image` (large)	Mixed	direct/link	All payloads preserved with correct transport
Ultimate Test	JavaScript	`text` (small) + `dictionary` (small) + `jsontable` (small) + `image` (small) + `audio` (small) + `video` (small) + `binary` (small) + `text` (large) + `dictionary` (large) + `jsontable` (large) + `image` (large)	Mixed	direct/link	All payloads preserved with correct transport
Ultimate Test	MicroPython	`text` (small) + `dictionary` (small) + `text` (large) + `dictionary` (large)	Mixed	direct	Limited to text/dictionary with direct transport only
Cross-platform JSON table	All	`jsontable`	Small	direct	Dictionary array round-trip
MicroPython ↔ Desktop	MicroPython ↔ Desktop	`text`/`dictionary`	Small	direct	Limited payload types
Desktop ↔ Desktop (all combos)	Julia↔JS↔Python	All types	Small/Large	direct/link	Full compatibility

Dependencies

Required Dependencies by Platform

Platform	Package	Version	Purpose
Julia	NATS.jl	Latest	NATS client
Julia	JSON.jl	Latest	JSON serialization
Julia	Arrow.jl	Latest	Arrow IPC support
Julia	HTTP.jl	Latest	HTTP file server
Julia	UUIDs.jl	Latest	UUID generation
Node.js	nats	Latest	NATS client
Node.js	node-fetch	Latest	HTTP file server
Python	nats-py	Latest	NATS client
Python	aiohttp	Latest	HTTP file server
Python	pyarrow	Latest	Arrow IPC support
MicroPython	builtin	N/A	Limited implementation

Optional Dependencies

Platform	Package	Purpose
Julia	DataFrames.jl	DataFrame support
Python	pandas	DataFrame support

Change Log

Date	Version	Changes
2026-03-13	1.0.0	Initial specification
-	-	Message envelope schema defined
-	-	Payload schema with transport modes
-	-	Enumerations for payload_type, transport, encoding
-	-	Size thresholds for desktop/MicroPython
-	-	Error codes and validation rules
-	-	API contracts for all platforms

References

docs/requirements.md - Business requirements and user stories
docs/architecture.md - System architecture diagrams
docs/implementation.md - Implementation details
src/NATSBridge.jl - Ground truth implementation
README.md - Project overview

Appendix

A. Complete JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "NATSBridge Envelope",
  "type": "object",
  "properties": {
    "correlation_id": {
      "type": "string",
      "pattern": "^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$",
      "description": "UUID v4 format for tracking message flow"
    },
    "msg_id": {
      "type": "string",
      "pattern": "^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$",
      "description": "Unique message identifier"
    },
    "timestamp": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
      "description": "ISO 8601 UTC timestamp"
    },
    "send_to": {
      "type": "string",
      "minLength": 1,
      "description": "NATS subject to publish to"
    },
    "msg_purpose": {
      "type": "string",
      "enum": ["ACK", "NACK", "updateStatus", "shutdown", "chat", "command", "event"],
      "description": "Purpose of the message"
    },
    "sender_name": {
      "type": "string",
      "minLength": 1,
      "description": "Sender application name"
    },
    "sender_id": {
      "type": "string",
      "pattern": "^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$",
      "description": "Sender UUID"
    },
    "receiver_name": {
      "type": "string",
      "description": "Receiver name (empty = broadcast)"
    },
    "receiver_id": {
      "type": "string",
      "pattern": "^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$|^$",
      "description": "Receiver UUID (empty = broadcast)"
    },
    "reply_to": {
      "type": "string",
      "description": "Topic for reply messages"
    },
    "reply_to_msg_id": {
      "type": "string",
      "description": "Message ID being replied to"
    },
    "broker_url": {
      "type": "string",
      "pattern": "^nats://[^\\s]+$",
      "description": "NATS broker URL"
    },
    "metadata": {
      "type": "object",
      "description": "Message-level metadata"
    },
    "payloads": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/Payload"
      }
    }
  },
  "required": ["correlation_id", "msg_id", "timestamp", "send_to", "msg_purpose", "sender_name", "sender_id", "receiver_name", "receiver_id", "reply_to", "reply_to_msg_id", "broker_url", "payloads"],
  "definitions": {
    "Payload": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$"
        },
        "dataname": {
          "type": "string",
          "minLength": 1
        },
        "payload_type": {
          "type": "string",
          "enum": ["text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"]
        },
        "transport": {
          "type": "string",
          "enum": ["direct", "link"]
        },
        "encoding": {
          "type": "string",
          "enum": ["none", "base64", "json", "arrow-ipc"]
        },
        "size": {
          "type": "integer",
          "minimum": 1
        },
        "data": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(https?://[^\\s]+)$"
            },
            {
              "type": "string",
              "pattern": "^[A-Za-z0-9+/]+=*$"
            }
          ]
        },
        "metadata": {
          "type": "object"
        }
      },
      "required": ["id", "dataname", "payload_type", "transport", "encoding", "size", "data"]
    }
  }
}

B. AsyncAPI Specification (NATS)

asyncapi: '2.6.0'
info:
  title: NATSBridge API
  version: '1.0.0'
  description: Cross-platform bi-directional data bridge using NATS
  contact:
    name: NATSBridge Team
    url: https://github.com/your-org/NATSBridge
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
channels:
  /agent/{service}/api/v{version}/{operation}:
    address: /agent/{service}/api/v{version}/{operation}
    parameters:
      service:
        schema:
          type: string
      version:
        schema:
          type: string
          enum: ['v1']
      operation:
        schema:
          type: string
    publish:
      summary: Publish message to NATS
      operationId: publishMessage
      message:
        $ref: '#/components/message'
    subscribe:
      summary: Subscribe to NATS messages
      operationId: subscribeMessage
      message:
        $ref: '#/components/message'
components:
  message:
    payload:
      $ref: '#/components/schemas/Envelope'
  schemas:
    Envelope:
      type: object
      properties:
        correlation_id:
          type: string
          format: uuid
        msg_id:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
        send_to:
          type: string
        msg_purpose:
          type: string
          enum: [ACK, NACK, updateStatus, shutdown, chat, command, event]
        sender_name:
          type: string
        sender_id:
          type: string
          format: uuid
        receiver_name:
          type: string
        receiver_id:
          type: string
          format: uuid
        reply_to:
          type: string
        reply_to_msg_id:
          type: string
        broker_url:
          type: string
        metadata:
          type: object
        payloads:
          type: array
          items:
            $ref: '#/components/schemas/Payload'
      required:
        - correlation_id
        - msg_id
        - timestamp
        - send_to
        - msg_purpose
        - sender_name
        - sender_id
        - receiver_name
        - receiver_id
        - reply_to
        - reply_to_msg_id
        - broker_url
        - payloads
    Payload:
      type: object
      properties:
        id:
          type: string
          format: uuid
        dataname:
          type: string
        payload_type:
          type: string
          enum: [text, dictionary, arrowtable, jsontable, image, audio, video, binary]
        transport:
          type: string
          enum: [direct, link]
        encoding:
          type: string
          enum: [none, base64, json, arrow-ipc]
        size:
          type: integer
          minimum: 1
        data:
          type: string
        metadata:
          type: object
      required:
        - id
        - dataname
        - payload_type
        - transport
        - encoding
        - size
        - data

This specification is versioned and maintained in git alongside the codebase. All implementations must adhere to this specification.

32 KiB Raw Blame History

Specification: NATSBridge

Executive Summary

Specification Versioning

Message Envelope Schema

Envelope Structure (JSON)

Field Definitions

Payload Schema

Payload Structure (JSON)

Payload Field Definitions

Payload Format

Tuple Format for smartsend()

Single Payload Example

Multiple Payloads Example

Data Type Mapping

Enumerations

msg_purpose Enum

payload_type Enum

transport Enum

encoding Enum

Transport Protocols

Direct Transport Protocol

Link Transport Protocol

Size Thresholds

Desktop Platforms (Julia/JS/Python)

MicroPython Platform

NATS Subject Convention

Subject Naming Pattern

Subject Wildcards

Error Handling

Error Response Format

Error Codes

Exception Handling

Serialization Rules

Text Serialization

Dictionary Serialization

Arrow Table Serialization

JSON Table Serialization

Binary Serialization

API Contract

smartsend Function Signature

Julia

Python

JavaScript (Node.js)

JavaScript (Browser)

MicroPython

smartreceive Function Signature

Julia

Python

JavaScript (Node.js)

JavaScript (Browser)

MicroPython

File Server Interface

Upload Handler Contract

Download Handler Contract

Platform-Specific Constraints

Desktop (Julia/JS/Python)

MicroPython

Message Flow

Sending Flow

Receiving Flow

Validation Rules

Envelope Validation

Payload Validation

Test Contracts

Unit Test Validation

Integration Test Scenarios

Dependencies

Required Dependencies by Platform

Optional Dependencies

Change Log

References

Appendix

A. Complete JSON Schema

B. AsyncAPI Specification (NATS)

32 KiB

Raw Blame History

Tuple Format for `smartsend()`

`msg_purpose` Enum

`payload_type` Enum

`transport` Enum

`encoding` Enum

`smartsend` Function Signature

`smartreceive` Function Signature