Files
herocoordinator/specs/openrpc.json
Lee Smet 2aa6277385 Actors are global
Signed-off-by: Lee Smet <lee.smet@hotmail.com>
2025-08-29 10:29:32 +02:00

1394 lines
31 KiB
JSON

{
"openrpc": "1.2.6",
"info": {
"title": "HeroCoordinator JSON-RPC API",
"version": "0.1.0",
"description": "JSON-RPC API over HTTP and WebSocket for creating and loading domain models. Host and ports are configurable via CLI flags."
},
"servers": [
{
"name": "http",
"url": "http://127.0.0.1:9652",
"summary": "Default HTTP server (configurable via --api-http-ip/--api-http-port)"
},
{
"name": "ws",
"url": "ws://127.0.0.1:9653",
"summary": "Default WS server (configurable via --api-ws-ip/--api-ws-port)"
}
],
"methods": [
{
"name": "actor.create",
"summary": "Create/Upsert Actor",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/ActorCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Actor"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "actor.load",
"summary": "Load an Actor by id",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/ActorLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Actor"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "context.create",
"summary": "Create/Upsert Context (stored in its own DB index)",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/ContextCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Context"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "context.load",
"summary": "Load a Context by id",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/ContextLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Context"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "runner.create",
"summary": "Create/Upsert Runner in a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/RunnerCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Runner"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "runner.load",
"summary": "Load Runner by id from a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/RunnerLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Runner"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "flow.create",
"summary": "Create/Upsert Flow in a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/FlowCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Flow"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "flow.load",
"summary": "Load Flow by id from a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/FlowLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Flow"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "flow.dag",
"summary": "Compute and return the execution DAG for a Flow",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/FlowLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/FlowDag"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
},
{
"$ref": "#/components/errors/DagMissingDependency"
},
{
"$ref": "#/components/errors/DagCycleDetected"
}
]
},
{
"name": "job.create",
"summary": "Create/Upsert Job in a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/JobCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Job"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "job.load",
"summary": "Load Job by ids from a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/JobLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Job"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "message.create",
"summary": "Create/Upsert Message in a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/MessageCreateParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Message"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/StorageError"
}
]
},
{
"name": "message.load",
"summary": "Load Message by ids from a context",
"params": [
{
"name": "params",
"schema": {
"$ref": "#/components/schemas/MessageLoadParams"
}
}
],
"result": {
"name": "result",
"schema": {
"$ref": "#/components/schemas/Message"
}
},
"errors": [
{
"$ref": "#/components/errors/InvalidParams"
},
{
"$ref": "#/components/errors/NotFound"
},
{
"$ref": "#/components/errors/StorageError"
}
]
}
],
"components": {
"schemas": {
"IpAddr": {
"type": "string",
"description": "IPv4 or IPv6 textual address"
},
"ScriptType": {
"type": "string",
"enum": [
"Osis",
"Sal",
"V",
"Python"
]
},
"FlowStatus": {
"type": "string",
"enum": [
"Dispatched",
"Started",
"Error",
"Finished"
]
},
"JobStatus": {
"type": "string",
"enum": [
"Dispatched",
"WaitingForPrerequisites",
"Started",
"Error",
"Finished"
]
},
"MessageFormatType": {
"type": "string",
"enum": [
"Html",
"Text",
"Md"
]
},
"MessageStatus": {
"type": "string",
"enum": [
"Dispatched",
"Acknowledged",
"Error",
"Processed"
]
},
"TransportStatus": {
"type": "string",
"enum": [
"Queued",
"Sent",
"Delivered",
"Read",
"Failed"
]
},
"MessageType": {
"type": "string",
"enum": [
"Job",
"Chat",
"Mail"
]
},
"Actor": {
"type": "object",
"required": [
"id",
"pubkey",
"address",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"pubkey": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IpAddr"
}
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
}
}
},
"Context": {
"type": "object",
"required": [
"id",
"admins",
"readers",
"executors",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"admins": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"readers": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"executors": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
}
}
},
"Runner": {
"type": "object",
"required": [
"id",
"pubkey",
"address",
"topic",
"local",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"pubkey": {
"type": "string"
},
"address": {
"$ref": "#/components/schemas/IpAddr"
},
"topic": {
"type": "string"
},
"local": {
"type": "boolean"
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
}
}
},
"Flow": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"jobs",
"env_vars",
"result",
"created_at",
"updated_at",
"status"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"jobs": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"env_vars": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"result": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
},
"status": {
"$ref": "#/components/schemas/FlowStatus"
}
}
},
"Job": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"script",
"script_type",
"timeout",
"retries",
"env_vars",
"result",
"prerequisites",
"depends",
"created_at",
"updated_at",
"status"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"script": {
"type": "string"
},
"script_type": {
"$ref": "#/components/schemas/ScriptType"
},
"timeout": {
"type": "integer",
"format": "uint32"
},
"retries": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"env_vars": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"result": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"prerequisites": {
"type": "array",
"items": {
"type": "string"
}
},
"depends": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
},
"status": {
"$ref": "#/components/schemas/JobStatus"
}
}
},
"Message": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"message",
"message_type",
"message_format_type",
"timeout",
"timeout_ack",
"timeout_result",
"job",
"logs",
"created_at",
"updated_at",
"status"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"message": {
"type": "string"
},
"message_type": {
"$ref": "#/components/schemas/ScriptType"
},
"message_format_type": {
"$ref": "#/components/schemas/MessageFormatType"
},
"timeout": {
"type": "integer",
"format": "uint32"
},
"timeout_ack": {
"type": "integer",
"format": "uint32"
},
"timeout_result": {
"type": "integer",
"format": "uint32"
},
"job": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
},
"logs": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "integer",
"format": "int64"
},
"status": {
"$ref": "#/components/schemas/MessageStatus"
},
"transport_id": {
"type": "string"
},
"transport_status": {
"$ref": "#/components/schemas/TransportStatus"
}
}
},
"JobSummary": {
"type": "object",
"required": [
"id",
"depends",
"prerequisites",
"script_type"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"depends": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"prerequisites": {
"type": "array",
"items": {
"type": "string"
}
},
"script_type": {
"$ref": "#/components/schemas/ScriptType"
}
}
},
"EdgeTuple": {
"type": "array",
"items": [
{
"type": "integer",
"format": "uint32"
},
{
"type": "integer",
"format": "uint32"
}
],
"minItems": 2,
"maxItems": 2,
"description": "Tuple [from, to] representing a directed edge"
},
"FlowDag": {
"type": "object",
"required": [
"flow_id",
"caller_id",
"context_id",
"nodes",
"edges",
"reverse_edges",
"roots",
"leaves",
"levels"
],
"properties": {
"flow_id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"nodes": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JobSummary"
},
"description": "Map keyed by job id (serialized as string in JSON)"
},
"edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EdgeTuple"
}
},
"reverse_edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EdgeTuple"
}
},
"roots": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"leaves": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"levels": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"description": "Topological execution layers (parallelizable batches)"
}
}
},
"ActorCreate": {
"type": "object",
"required": [
"id",
"pubkey",
"address"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"pubkey": {
"type": "string"
},
"address": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IpAddr"
}
}
}
},
"ContextCreate": {
"type": "object",
"required": [
"id",
"admins",
"readers",
"executors"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"admins": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"readers": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"executors": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
}
}
},
"RunnerCreate": {
"type": "object",
"required": [
"id",
"pubkey",
"address",
"topic",
"local"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"pubkey": {
"type": "string"
},
"address": {
"$ref": "#/components/schemas/IpAddr"
},
"topic": {
"type": "string"
},
"local": {
"type": "boolean"
}
}
},
"FlowCreate": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"jobs",
"env_vars"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"jobs": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
},
"env_vars": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"result": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"JobCreate": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"script",
"script_type",
"timeout",
"retries",
"env_vars",
"prerequisites",
"depends"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"script": {
"type": "string"
},
"script_type": {
"$ref": "#/components/schemas/ScriptType"
},
"timeout": {
"type": "integer",
"format": "uint32"
},
"retries": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"env_vars": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"result": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"prerequisites": {
"type": "array",
"items": {
"type": "string"
}
},
"depends": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32"
}
}
}
},
"MessageCreate": {
"type": "object",
"required": [
"id",
"caller_id",
"context_id",
"message",
"message_type",
"message_format_type",
"timeout",
"timeout_ack",
"timeout_result",
"job"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"context_id": {
"type": "integer",
"format": "uint32"
},
"message": {
"type": "string"
},
"message_type": {
"$ref": "#/components/schemas/ScriptType"
},
"message_format_type": {
"$ref": "#/components/schemas/MessageFormatType"
},
"timeout": {
"type": "integer",
"format": "uint32"
},
"timeout_ack": {
"type": "integer",
"format": "uint32"
},
"timeout_result": {
"type": "integer",
"format": "uint32"
},
"job": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobCreate"
}
},
"logs": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ActorCreateParams": {
"type": "object",
"required": [
"actor"
],
"properties": {
"actor": {
"$ref": "#/components/schemas/ActorCreate"
}
}
},
"ActorLoadParams": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
}
}
},
"ContextCreateParams": {
"type": "object",
"required": [
"context"
],
"properties": {
"context": {
"$ref": "#/components/schemas/ContextCreate"
}
}
},
"ContextLoadParams": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "uint32"
}
}
},
"RunnerCreateParams": {
"type": "object",
"required": [
"context_id",
"runner"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"runner": {
"$ref": "#/components/schemas/RunnerCreate"
}
}
},
"RunnerLoadParams": {
"type": "object",
"required": [
"context_id",
"id"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"id": {
"type": "integer",
"format": "uint32"
}
}
},
"FlowCreateParams": {
"type": "object",
"required": [
"context_id",
"flow"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"flow": {
"$ref": "#/components/schemas/FlowCreate"
}
}
},
"FlowLoadParams": {
"type": "object",
"required": [
"context_id",
"id"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"id": {
"type": "integer",
"format": "uint32"
}
}
},
"JobCreateParams": {
"type": "object",
"required": [
"context_id",
"job"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"job": {
"$ref": "#/components/schemas/JobCreate"
}
}
},
"JobLoadParams": {
"type": "object",
"required": [
"context_id",
"caller_id",
"id"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"id": {
"type": "integer",
"format": "uint32"
}
}
},
"MessageCreateParams": {
"type": "object",
"required": [
"context_id",
"message"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"message": {
"$ref": "#/components/schemas/MessageCreate"
}
}
},
"MessageLoadParams": {
"type": "object",
"required": [
"context_id",
"caller_id",
"id"
],
"properties": {
"context_id": {
"type": "integer",
"format": "uint32"
},
"caller_id": {
"type": "integer",
"format": "uint32"
},
"id": {
"type": "integer",
"format": "uint32"
}
}
}
},
"errors": {
"InvalidParams": {
"code": -32602,
"message": "Invalid params"
},
"NotFound": {
"code": -32001,
"message": "Not Found"
},
"StorageError": {
"code": -32010,
"message": "Storage Error"
},
"DagMissingDependency": {
"code": -32020,
"message": "DAG Missing Dependency"
},
"DagCycleDetected": {
"code": -32021,
"message": "DAG Cycle Detected"
}
}
}
}