Skip to content

Commit 123ffbc

Browse files
JulusianJulusian
committed
wip: poc
1 parent 54e04f1 commit 123ffbc

24 files changed

Lines changed: 4459 additions & 0 deletions

‎apps/package-manager-api/asyncapi/asyncapi.yaml‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
asyncapi: '3.1.0'
2+
3+
info:
4+
title: Sofie Package Manager API
5+
version: 1.0.0
6+
description: >
7+
WebSocket API between **Sofie Core** and the **Package Manager**.
8+
9+
## Overview
10+
11+
This document describes the full message contract for the Package Manager API.
12+
The Package Manager (PM) connects to Sofie Core over a persistent WebSocket
13+
connection. Once connected, both sides exchange messages on named logical channels.
14+
15+
## Authentication / identification
16+
17+
Each Package Manager instance identifies itself at connection time via query
18+
parameters on the WebSocket handshake URL:
19+
20+
| Query param | Type | Description |
21+
|---------------|--------|--------------------------------------------------|
22+
| `clientId` | string | Stable identifier for this PM instance |
23+
| `expectationManagerId` | string | The Expectation Manager this PM hosts |
24+
25+
No token-based authentication is defined here — network-level controls
26+
(firewall, VPN, mutual TLS) are assumed.
27+
28+
## Channel overview
29+
30+
| Channel address | Direction | Pattern | Description |
31+
|--------------------------|-------------|-------------------|-----------------------------------------|
32+
| `expectations` | Core → PM | Event (CRUD) | Expectation lifecycle deltas |
33+
| `packageContainers` | Core → PM | Event (CRUD) | PackageContainer config deltas |
34+
| `workStatuses` | PM → Core | Event (CRUD) | ExpectationStatus lifecycle deltas |
35+
| `containerStatuses` | PM → Core | Event (update/rm) | PackageContainer health status |
36+
| `containerPackageStatuses` | PM → Core | Event (update/rm) | Per-package transfer status |
37+
| `packageInfo` | PM → Core | Event (fire-forget)| Scan/probe results and removals |
38+
| `rpc/core-to-pm` | Bidirectional | JSON-RPC 2.0 | Core calls RPC methods on PM (7 methods)|
39+
| `rpc/pm-to-core` | Bidirectional | JSON-RPC 2.0 | PM calls RPC methods on Core (1 method) |
40+
41+
## Design constraints
42+
43+
- There is **no** `ExpectedPackageId` in the protocol. All statuses and
44+
package-info entries are keyed by `ExpectationId`. Core maps back to its
45+
own expected packages internally.
46+
- There is **no** `requiredForPlayout` field. Urgency is expressed via the
47+
numeric `priority` field.
48+
- JSON-RPC 2.0 is used for request-reply RPC calls. The `id` field on the
49+
JSON-RPC envelope correlates requests to responses.
50+
51+
license:
52+
name: MIT
53+
url: https://opensource.org/licenses/MIT
54+
55+
servers:
56+
coreWebSocket:
57+
host: '{coreHost}:{corePort}'
58+
pathname: /package-manager
59+
protocol: wss
60+
description: >
61+
Sofie Core WebSocket endpoint for the Package Manager API.
62+
The Package Manager connects here. Both parties then exchange messages
63+
across the channels defined below.
64+
variables:
65+
coreHost:
66+
description: Hostname or IP address of the Sofie Core server.
67+
default: localhost
68+
corePort:
69+
description: WebSocket port for the Package Manager API.
70+
default: '3000'
71+
72+
# ---------------------------------------------------------------------------
73+
# Channels
74+
# ---------------------------------------------------------------------------
75+
channels:
76+
# Core → PM event channels
77+
expectations:
78+
$ref: './channels/from-core.yaml#/expectations'
79+
packageContainers:
80+
$ref: './channels/from-core.yaml#/packageContainers'
81+
82+
# PM → Core event channels
83+
workStatuses:
84+
$ref: './channels/from-pm.yaml#/workStatuses'
85+
containerStatuses:
86+
$ref: './channels/from-pm.yaml#/containerStatuses'
87+
containerPackageStatuses:
88+
$ref: './channels/from-pm.yaml#/containerPackageStatuses'
89+
packageInfo:
90+
$ref: './channels/from-pm.yaml#/packageInfo'
91+
92+
# JSON-RPC channels
93+
rpcCoreTopm:
94+
$ref: './channels/rpc-core-to-pm.yaml#/rpcCoreTopm'
95+
rpcPmToCore:
96+
$ref: './channels/rpc-pm-to-core.yaml#/rpcPmToCore'
97+
98+
# ---------------------------------------------------------------------------
99+
# Operations — from Core's perspective
100+
# ---------------------------------------------------------------------------
101+
operations:
102+
# Core → PM sends
103+
sendExpectationAdded:
104+
$ref: './operations/from-core.yaml#/sendExpectationAdded'
105+
sendExpectationUpdated:
106+
$ref: './operations/from-core.yaml#/sendExpectationUpdated'
107+
sendExpectationRemoved:
108+
$ref: './operations/from-core.yaml#/sendExpectationRemoved'
109+
sendPackageContainerAdded:
110+
$ref: './operations/from-core.yaml#/sendPackageContainerAdded'
111+
sendPackageContainerUpdated:
112+
$ref: './operations/from-core.yaml#/sendPackageContainerUpdated'
113+
sendPackageContainerRemoved:
114+
$ref: './operations/from-core.yaml#/sendPackageContainerRemoved'
115+
116+
# Core receives from PM
117+
receiveExpectationStatusAdded:
118+
$ref: './operations/from-core.yaml#/receiveExpectationStatusAdded'
119+
receiveExpectationStatusUpdated:
120+
$ref: './operations/from-core.yaml#/receiveExpectationStatusUpdated'
121+
receiveExpectationStatusRemoved:
122+
$ref: './operations/from-core.yaml#/receiveExpectationStatusRemoved'
123+
receiveContainerStatusUpdated:
124+
$ref: './operations/from-core.yaml#/receiveContainerStatusUpdated'
125+
receiveContainerStatusRemoved:
126+
$ref: './operations/from-core.yaml#/receiveContainerStatusRemoved'
127+
receiveContainerPackageStatusUpdated:
128+
$ref: './operations/from-core.yaml#/receiveContainerPackageStatusUpdated'
129+
receiveContainerPackageStatusRemoved:
130+
$ref: './operations/from-core.yaml#/receiveContainerPackageStatusRemoved'
131+
receivePackageInfoUpdated:
132+
$ref: './operations/from-core.yaml#/receivePackageInfoUpdated'
133+
receivePackageInfoRemoved:
134+
$ref: './operations/from-core.yaml#/receivePackageInfoRemoved'
135+
136+
# Core RPC (send requests, receive responses)
137+
sendRpcCoreTopm:
138+
$ref: './operations/from-core.yaml#/sendRpcCoreTopm'
139+
receiveRpcCoreTopmResponse:
140+
$ref: './operations/from-core.yaml#/receiveRpcCoreTopmResponse'
141+
142+
# Core answers PM's RPC calls
143+
receiveRpcPmToCoreRequest:
144+
$ref: './operations/from-core.yaml#/receiveRpcPmToCoreRequest'
145+
sendRpcPmToCoreResponse:
146+
$ref: './operations/from-core.yaml#/sendRpcPmToCoreResponse'
147+
148+
# ---------------------------------------------------------------------------
149+
# Components — inline references for tooling convenience.
150+
# Full schemas live under ./components/schemas/*.yaml
151+
# ---------------------------------------------------------------------------
152+
components:
153+
schemas:
154+
# IDs
155+
ExpectationId:
156+
$ref: './components/schemas/ids.yaml#/ExpectationId'
157+
ExpectationManagerId:
158+
$ref: './components/schemas/ids.yaml#/ExpectationManagerId'
159+
PackageContainerId:
160+
$ref: './components/schemas/ids.yaml#/PackageContainerId'
161+
AccessorId:
162+
$ref: './components/schemas/ids.yaml#/AccessorId'
163+
WorkerAgentId:
164+
$ref: './components/schemas/ids.yaml#/WorkerAgentId'
165+
WorkInProgressId:
166+
$ref: './components/schemas/ids.yaml#/WorkInProgressId'
167+
WorkInProgressLocalId:
168+
$ref: './components/schemas/ids.yaml#/WorkInProgressLocalId'
169+
MonitorId:
170+
$ref: './components/schemas/ids.yaml#/MonitorId'
171+
AppContainerId:
172+
$ref: './components/schemas/ids.yaml#/AppContainerId'
173+
AppId:
174+
$ref: './components/schemas/ids.yaml#/AppId'
175+
176+
# Common
177+
WorkStatusState:
178+
$ref: './components/schemas/common.yaml#/WorkStatusState'
179+
StatusCode:
180+
$ref: './components/schemas/common.yaml#/StatusCode'
181+
Reason:
182+
$ref: './components/schemas/common.yaml#/Reason'
183+
Priority:
184+
$ref: './components/schemas/common.yaml#/Priority'
185+
186+
# JSON-RPC
187+
JsonRpcRequest:
188+
$ref: './components/schemas/jsonrpc.yaml#/JsonRpcRequest'
189+
JsonRpcResponse:
190+
$ref: './components/schemas/jsonrpc.yaml#/JsonRpcResponse'
191+
JsonRpcError:
192+
$ref: './components/schemas/jsonrpc.yaml#/JsonRpcError'
193+
194+
# Domain
195+
Expectation:
196+
$ref: './components/schemas/expectations/index.yaml#/Expectation'
197+
PackageContainer:
198+
$ref: './components/schemas/package-containers.yaml#/PackageContainer'
199+
PackageContainerExpectation:
200+
$ref: './components/schemas/package-containers.yaml#/PackageContainerExpectation'
201+
ExpectationStatus:
202+
$ref: './components/schemas/statuses.yaml#/ExpectationStatus'
203+
PackageContainerStatus:
204+
$ref: './components/schemas/statuses.yaml#/PackageContainerStatus'
205+
PackageContainerPackageStatus:
206+
$ref: './components/schemas/statuses.yaml#/PackageContainerPackageStatus'
207+
ExpectationManagerStatusReport:
208+
$ref: './components/schemas/statuses.yaml#/ExpectationManagerStatusReport'
209+
PackageInfoEntry:
210+
$ref: './components/schemas/statuses.yaml#/PackageInfoEntry'

‎apps/package-manager-api/asyncapi/channels/from-core.yaml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Channels carrying messages FROM Sofie Core TO the Package Manager.
2+
#
3+
# Core is the sender on both channels.
4+
# PM subscribes and handles the events.
5+
#
6+
# AsyncAPI 3.x: channels declare the *address* and the messages that
7+
# flow through them. Operations (send/receive) are defined separately.
8+
9+
expectations:
10+
address: expectations
11+
title: Expectations Channel
12+
description: >
13+
Sofie Core sends CRUD-delta events for Expectations over this channel.
14+
The Package Manager maintains a local mirror of the expectation set and
15+
reacts to each delta immediately.
16+
messages:
17+
ExpectationAdded:
18+
$ref: '../components/messages/from-core-messages.yaml#/ExpectationAdded'
19+
ExpectationUpdated:
20+
$ref: '../components/messages/from-core-messages.yaml#/ExpectationUpdated'
21+
ExpectationRemoved:
22+
$ref: '../components/messages/from-core-messages.yaml#/ExpectationRemoved'
23+
24+
packageContainers:
25+
address: packageContainers
26+
title: Package Containers Channel
27+
description: >
28+
Sofie Core sends CRUD-delta events for PackageContainerExpectations over
29+
this channel. Each entry carries the full monitor and cron configuration
30+
that the PM needs to set up file-watching and scheduled cleanup tasks.
31+
messages:
32+
PackageContainerAdded:
33+
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerAdded'
34+
PackageContainerUpdated:
35+
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerUpdated'
36+
PackageContainerRemoved:
37+
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerRemoved'

‎apps/package-manager-api/asyncapi/channels/from-pm.yaml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Channels carrying messages FROM the Package Manager TO Sofie Core.
2+
#
3+
# PM is the sender on all channels.
4+
# Core subscribes and handles the events.
5+
#
6+
# AsyncAPI 3.x: channels declare the *address* and the messages that
7+
# flow through them. Operations (send/receive) are defined separately.
8+
9+
workStatuses:
10+
address: workStatuses
11+
title: Work Statuses Channel
12+
description: >
13+
The Package Manager sends CRUD-delta events for ExpectationStatus objects
14+
over this channel. Core maintains a live view of all expectation statuses,
15+
keyed by ExpectationId.
16+
messages:
17+
ExpectationStatusAdded:
18+
$ref: '../components/messages/from-pm-messages.yaml#/ExpectationStatusAdded'
19+
ExpectationStatusUpdated:
20+
$ref: '../components/messages/from-pm-messages.yaml#/ExpectationStatusUpdated'
21+
ExpectationStatusRemoved:
22+
$ref: '../components/messages/from-pm-messages.yaml#/ExpectationStatusRemoved'
23+
24+
containerStatuses:
25+
address: containerStatuses
26+
title: Container Statuses Channel
27+
description: >
28+
The Package Manager reports the health of each PackageContainer, including
29+
the status of any monitors running on it.
30+
messages:
31+
ContainerStatusUpdated:
32+
$ref: '../components/messages/from-pm-messages.yaml#/ContainerStatusUpdated'
33+
ContainerStatusRemoved:
34+
$ref: '../components/messages/from-pm-messages.yaml#/ContainerStatusRemoved'
35+
36+
containerPackageStatuses:
37+
address: containerPackageStatuses
38+
title: Container Package Statuses Channel
39+
description: >
40+
The Package Manager reports per-package transfer status within each
41+
PackageContainer (e.g. copy in progress, copy complete, placeholder ready).
42+
messages:
43+
ContainerPackageStatusUpdated:
44+
$ref: '../components/messages/from-pm-messages.yaml#/ContainerPackageStatusUpdated'
45+
ContainerPackageStatusRemoved:
46+
$ref: '../components/messages/from-pm-messages.yaml#/ContainerPackageStatusRemoved'
47+
48+
packageInfo:
49+
address: packageInfo
50+
title: Package Info Channel
51+
description: >
52+
The Package Manager fires scan/probe results (and removals) to Core on
53+
this channel. These are fire-and-forget events; no acknowledgement is
54+
returned. Core stores the payloads in its package-info collection, keyed
55+
by ExpectationId.
56+
messages:
57+
PackageInfoUpdated:
58+
$ref: '../components/messages/from-pm-messages.yaml#/PackageInfoUpdated'
59+
PackageInfoRemoved:
60+
$ref: '../components/messages/from-pm-messages.yaml#/PackageInfoRemoved'

‎apps/package-manager-api/asyncapi/channels/rpc-core-to-pm.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# RPC channel: Core → Package Manager.
2+
#
3+
# Core sends JSON-RPC 2.0 Requests; PM sends JSON-RPC 2.0 Responses.
4+
# Both directions share the same WebSocket channel address.
5+
# Callers correlate requests and responses using the JSON-RPC `id` field.
6+
#
7+
# 7 methods: restartExpectation, restartAllExpectations, abortExpectation,
8+
# restartPackageContainer, troubleshoot, getExpectationManagerStatus,
9+
# debugKillApp
10+
11+
rpcCoreTopm:
12+
address: rpc/core-to-pm
13+
title: RPC Channel — Core to Package Manager
14+
description: >
15+
Bidirectional JSON-RPC 2.0 channel where Sofie Core is the caller.
16+
Core sends Request objects; the Package Manager sends Response objects.
17+
Both message types share this channel; the JSON-RPC `id` field correlates them.
18+
messages:
19+
# Requests (Core → PM)
20+
RestartExpectationRequest:
21+
$ref: '../components/messages/rpc-messages.yaml#/RestartExpectationRequest'
22+
RestartAllExpectationsRequest:
23+
$ref: '../components/messages/rpc-messages.yaml#/RestartAllExpectationsRequest'
24+
AbortExpectationRequest:
25+
$ref: '../components/messages/rpc-messages.yaml#/AbortExpectationRequest'
26+
RestartPackageContainerRequest:
27+
$ref: '../components/messages/rpc-messages.yaml#/RestartPackageContainerRequest'
28+
TroubleshootRequest:
29+
$ref: '../components/messages/rpc-messages.yaml#/TroubleshootRequest'
30+
GetExpectationManagerStatusRequest:
31+
$ref: '../components/messages/rpc-messages.yaml#/GetExpectationManagerStatusRequest'
32+
DebugKillAppRequest:
33+
$ref: '../components/messages/rpc-messages.yaml#/DebugKillAppRequest'
34+
# Responses (PM → Core)
35+
RestartExpectationResponse:
36+
$ref: '../components/messages/rpc-messages.yaml#/RestartExpectationResponse'
37+
RestartAllExpectationsResponse:
38+
$ref: '../components/messages/rpc-messages.yaml#/RestartAllExpectationsResponse'
39+
AbortExpectationResponse:
40+
$ref: '../components/messages/rpc-messages.yaml#/AbortExpectationResponse'
41+
RestartPackageContainerResponse:
42+
$ref: '../components/messages/rpc-messages.yaml#/RestartPackageContainerResponse'
43+
TroubleshootResponse:
44+
$ref: '../components/messages/rpc-messages.yaml#/TroubleshootResponse'
45+
GetExpectationManagerStatusResponse:
46+
$ref: '../components/messages/rpc-messages.yaml#/GetExpectationManagerStatusResponse'
47+
DebugKillAppResponse:
48+
$ref: '../components/messages/rpc-messages.yaml#/DebugKillAppResponse'

‎apps/package-manager-api/asyncapi/channels/rpc-pm-to-core.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# RPC channel: Package Manager → Core.
2+
#
3+
# PM sends JSON-RPC 2.0 Requests; Core sends JSON-RPC 2.0 Responses.
4+
# Both directions share the same WebSocket channel address.
5+
# Callers correlate requests and responses using the JSON-RPC `id` field.
6+
#
7+
# 1 method: fetchPackageInfoMetadata
8+
9+
rpcPmToCore:
10+
address: rpc/pm-to-core
11+
title: RPC Channel — Package Manager to Core
12+
description: >
13+
Bidirectional JSON-RPC 2.0 channel where the Package Manager is the caller.
14+
PM sends Request objects; Sofie Core sends Response objects.
15+
Both message types share this channel; the JSON-RPC `id` field correlates them.
16+
messages:
17+
# Request (PM → Core)
18+
FetchPackageInfoMetadataRequest:
19+
$ref: '../components/messages/rpc-messages.yaml#/FetchPackageInfoMetadataRequest'
20+
# Response (Core → PM)
21+
FetchPackageInfoMetadataResponse:
22+
$ref: '../components/messages/rpc-messages.yaml#/FetchPackageInfoMetadataResponse'

0 commit comments

Comments
 (0)