Skip to content

Commit 84873d9

Browse files
JulusianCopilot
Julusian
and
Copilot
committed
wip: naming
Co-authored-by: Copilot <copilot@github.com>
1 parent 123ffbc commit 84873d9

21 files changed

Lines changed: 372 additions & 378 deletions

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

Lines changed: 60 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,14 @@ info:
44
title: Sofie Package Manager API
55
version: 1.0.0
66
description: >
7-
WebSocket API between **Sofie Core** and the **Package Manager**.
7+
WebSocket API between an **external consumer** and the **Package Manager**.
88
99
## Overview
1010
1111
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.
12+
An external consumer (e.g. Sofie Core or any other application) connects to the
13+
Package Manager (PM) over a persistent WebSocket connection. Once connected,
14+
both sides exchange messages on named logical channels.
1415
1516
## Authentication / identification
1617
@@ -20,7 +21,6 @@ info:
2021
| Query param | Type | Description |
2122
|---------------|--------|--------------------------------------------------|
2223
| `clientId` | string | Stable identifier for this PM instance |
23-
| `expectationManagerId` | string | The Expectation Manager this PM hosts |
2424
2525
No token-based authentication is defined here — network-level controls
2626
(firewall, VPN, mutual TLS) are assumed.
@@ -29,22 +29,17 @@ info:
2929
3030
| Channel address | Direction | Pattern | Description |
3131
|--------------------------|-------------|-------------------|-----------------------------------------|
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) |
32+
| `expectations` | Consumer → PM | Event (CRUD) | Expectation lifecycle deltas |
33+
| `packageContainers` | Consumer → PM | Event (CRUD) | PackageContainer config deltas |
34+
| `workStatuses` | PM → Consumer | Event (CRUD) | ExpectationStatus lifecycle deltas |
35+
| `containerStatuses` | PM → Consumer | Event (update/rm) | PackageContainer health status |
36+
| `containerPackageStatuses` | PM → Consumer | Event (update/rm) | Per-package transfer status |
37+
| `packageInfo` | PM → Consumer | Event (fire-forget)| Scan/probe results and removals |
38+
| `rpc/consumer-to-pm` | Bidirectional | JSON-RPC 2.0 | Consumer calls RPC methods on PM (7 methods)|
39+
| `rpc/pm-to-consumer` | Bidirectional | JSON-RPC 2.0 | PM calls RPC methods on consumer (1 method) |
4040
4141
## Design constraints
4242
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.
4843
- JSON-RPC 2.0 is used for request-reply RPC calls. The `id` field on the
4944
JSON-RPC envelope correlates requests to responses.
5045
@@ -53,33 +48,32 @@ info:
5348
url: https://opensource.org/licenses/MIT
5449

5550
servers:
56-
coreWebSocket:
57-
host: '{coreHost}:{corePort}'
58-
pathname: /package-manager
51+
packageManagerApiWebSocket:
52+
host: '{pmApiHost}:{pmApiPort}'
53+
pathname: /
5954
protocol: wss
6055
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.
56+
WebSocket endpoint exposed by the Package Manager API.
57+
The external consumer connects here as a client.
6458
variables:
65-
coreHost:
66-
description: Hostname or IP address of the Sofie Core server.
59+
pmApiHost:
60+
description: Hostname or IP address of the Package Manager API.
6761
default: localhost
68-
corePort:
69-
description: WebSocket port for the Package Manager API.
70-
default: '3000'
62+
pmApiPort:
63+
description: WebSocket port exposed by the Package Manager API.
64+
default: '8080'
7165

7266
# ---------------------------------------------------------------------------
7367
# Channels
7468
# ---------------------------------------------------------------------------
7569
channels:
76-
# Core → PM event channels
70+
# Consumer → PM event channels
7771
expectations:
78-
$ref: './channels/from-core.yaml#/expectations'
72+
$ref: './channels/from-consumer.yaml#/expectations'
7973
packageContainers:
80-
$ref: './channels/from-core.yaml#/packageContainers'
74+
$ref: './channels/from-consumer.yaml#/packageContainers'
8175

82-
# PM → Core event channels
76+
# PM → Consumer event channels
8377
workStatuses:
8478
$ref: './channels/from-pm.yaml#/workStatuses'
8579
containerStatuses:
@@ -90,60 +84,60 @@ channels:
9084
$ref: './channels/from-pm.yaml#/packageInfo'
9185

9286
# 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'
87+
rpcConsumerToPm:
88+
$ref: './channels/rpc-consumer-to-pm.yaml#/rpcConsumerToPm'
89+
rpcPmToConsumer:
90+
$ref: './channels/rpc-pm-to-consumer.yaml#/rpcPmToConsumer'
9791

9892
# ---------------------------------------------------------------------------
99-
# Operations — from Core's perspective
93+
# Operations — from the consumer's perspective
10094
# ---------------------------------------------------------------------------
10195
operations:
102-
# Core → PM sends
96+
# Consumer → PM sends
10397
sendExpectationAdded:
104-
$ref: './operations/from-core.yaml#/sendExpectationAdded'
98+
$ref: './operations/from-consumer.yaml#/sendExpectationAdded'
10599
sendExpectationUpdated:
106-
$ref: './operations/from-core.yaml#/sendExpectationUpdated'
100+
$ref: './operations/from-consumer.yaml#/sendExpectationUpdated'
107101
sendExpectationRemoved:
108-
$ref: './operations/from-core.yaml#/sendExpectationRemoved'
102+
$ref: './operations/from-consumer.yaml#/sendExpectationRemoved'
109103
sendPackageContainerAdded:
110-
$ref: './operations/from-core.yaml#/sendPackageContainerAdded'
104+
$ref: './operations/from-consumer.yaml#/sendPackageContainerAdded'
111105
sendPackageContainerUpdated:
112-
$ref: './operations/from-core.yaml#/sendPackageContainerUpdated'
106+
$ref: './operations/from-consumer.yaml#/sendPackageContainerUpdated'
113107
sendPackageContainerRemoved:
114-
$ref: './operations/from-core.yaml#/sendPackageContainerRemoved'
108+
$ref: './operations/from-consumer.yaml#/sendPackageContainerRemoved'
115109

116-
# Core receives from PM
110+
# Consumer receives from PM
117111
receiveExpectationStatusAdded:
118-
$ref: './operations/from-core.yaml#/receiveExpectationStatusAdded'
112+
$ref: './operations/from-consumer.yaml#/receiveExpectationStatusAdded'
119113
receiveExpectationStatusUpdated:
120-
$ref: './operations/from-core.yaml#/receiveExpectationStatusUpdated'
114+
$ref: './operations/from-consumer.yaml#/receiveExpectationStatusUpdated'
121115
receiveExpectationStatusRemoved:
122-
$ref: './operations/from-core.yaml#/receiveExpectationStatusRemoved'
116+
$ref: './operations/from-consumer.yaml#/receiveExpectationStatusRemoved'
123117
receiveContainerStatusUpdated:
124-
$ref: './operations/from-core.yaml#/receiveContainerStatusUpdated'
118+
$ref: './operations/from-consumer.yaml#/receiveContainerStatusUpdated'
125119
receiveContainerStatusRemoved:
126-
$ref: './operations/from-core.yaml#/receiveContainerStatusRemoved'
120+
$ref: './operations/from-consumer.yaml#/receiveContainerStatusRemoved'
127121
receiveContainerPackageStatusUpdated:
128-
$ref: './operations/from-core.yaml#/receiveContainerPackageStatusUpdated'
122+
$ref: './operations/from-consumer.yaml#/receiveContainerPackageStatusUpdated'
129123
receiveContainerPackageStatusRemoved:
130-
$ref: './operations/from-core.yaml#/receiveContainerPackageStatusRemoved'
124+
$ref: './operations/from-consumer.yaml#/receiveContainerPackageStatusRemoved'
131125
receivePackageInfoUpdated:
132-
$ref: './operations/from-core.yaml#/receivePackageInfoUpdated'
126+
$ref: './operations/from-consumer.yaml#/receivePackageInfoUpdated'
133127
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'
128+
$ref: './operations/from-consumer.yaml#/receivePackageInfoRemoved'
129+
130+
# Consumer RPC (send requests, receive responses)
131+
sendRpcConsumerToPm:
132+
$ref: './operations/from-consumer.yaml#/sendRpcConsumerToPm'
133+
receiveRpcConsumerToPmResponse:
134+
$ref: './operations/from-consumer.yaml#/receiveRpcConsumerToPmResponse'
135+
136+
# Consumer answers PM's RPC calls
137+
receiveRpcPmToConsumerRequest:
138+
$ref: './operations/from-consumer.yaml#/receiveRpcPmToConsumerRequest'
139+
sendRpcPmToConsumerResponse:
140+
$ref: './operations/from-consumer.yaml#/sendRpcPmToConsumerResponse'
147141

148142
# ---------------------------------------------------------------------------
149143
# Components — inline references for tooling convenience.

apps/package-manager-api/asyncapi/channels/from-core.yaml renamed to apps/package-manager-api/asyncapi/channels/from-consumer.yaml

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Channels carrying messages FROM Sofie Core TO the Package Manager.
1+
# Channels carrying messages FROM the consumer TO the Package Manager.
22
#
3-
# Core is the sender on both channels.
3+
# The consumer is the sender on both channels.
44
# PM subscribes and handles the events.
55
#
66
# AsyncAPI 3.x: channels declare the *address* and the messages that
@@ -10,28 +10,28 @@ expectations:
1010
address: expectations
1111
title: Expectations Channel
1212
description: >
13-
Sofie Core sends CRUD-delta events for Expectations over this channel.
13+
The consumer sends CRUD-delta events for Expectations over this channel.
1414
The Package Manager maintains a local mirror of the expectation set and
1515
reacts to each delta immediately.
1616
messages:
1717
ExpectationAdded:
18-
$ref: '../components/messages/from-core-messages.yaml#/ExpectationAdded'
18+
$ref: '../components/messages/from-consumer-messages.yaml#/ExpectationAdded'
1919
ExpectationUpdated:
20-
$ref: '../components/messages/from-core-messages.yaml#/ExpectationUpdated'
20+
$ref: '../components/messages/from-consumer-messages.yaml#/ExpectationUpdated'
2121
ExpectationRemoved:
22-
$ref: '../components/messages/from-core-messages.yaml#/ExpectationRemoved'
22+
$ref: '../components/messages/from-consumer-messages.yaml#/ExpectationRemoved'
2323

2424
packageContainers:
2525
address: packageContainers
2626
title: Package Containers Channel
2727
description: >
28-
Sofie Core sends CRUD-delta events for PackageContainerExpectations over
28+
The consumer sends CRUD-delta events for PackageContainerExpectations over
2929
this channel. Each entry carries the full monitor and cron configuration
3030
that the PM needs to set up file-watching and scheduled cleanup tasks.
3131
messages:
3232
PackageContainerAdded:
33-
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerAdded'
33+
$ref: '../components/messages/from-consumer-messages.yaml#/PackageContainerAdded'
3434
PackageContainerUpdated:
35-
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerUpdated'
35+
$ref: '../components/messages/from-consumer-messages.yaml#/PackageContainerUpdated'
3636
PackageContainerRemoved:
37-
$ref: '../components/messages/from-core-messages.yaml#/PackageContainerRemoved'
37+
$ref: '../components/messages/from-consumer-messages.yaml#/PackageContainerRemoved'

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# Channels carrying messages FROM the Package Manager TO Sofie Core.
1+
# Channels carrying messages FROM the Package Manager TO the consumer.
22
#
33
# PM is the sender on all channels.
4-
# Core subscribes and handles the events.
4+
# The consumer subscribes and handles the events.
55
#
66
# AsyncAPI 3.x: channels declare the *address* and the messages that
77
# flow through them. Operations (send/receive) are defined separately.
@@ -11,7 +11,7 @@ workStatuses:
1111
title: Work Statuses Channel
1212
description: >
1313
The Package Manager sends CRUD-delta events for ExpectationStatus objects
14-
over this channel. Core maintains a live view of all expectation statuses,
14+
over this channel. The consumer maintains a live view of all expectation statuses,
1515
keyed by ExpectationId.
1616
messages:
1717
ExpectationStatusAdded:
@@ -49,9 +49,9 @@ packageInfo:
4949
address: packageInfo
5050
title: Package Info Channel
5151
description: >
52-
The Package Manager fires scan/probe results (and removals) to Core on
52+
The Package Manager fires scan/probe results (and removals) to the consumer on
5353
this channel. These are fire-and-forget events; no acknowledgement is
54-
returned. Core stores the payloads in its package-info collection, keyed
54+
returned. The consumer stores the payloads in its package-info collection, keyed
5555
by ExpectationId.
5656
messages:
5757
PackageInfoUpdated:

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
1-
# RPC channel: Core → Package Manager.
1+
# RPC channel: Consumer → Package Manager.
22
#
3-
# Core sends JSON-RPC 2.0 Requests; PM sends JSON-RPC 2.0 Responses.
3+
# The consumer sends JSON-RPC 2.0 Requests; PM sends JSON-RPC 2.0 Responses.
44
# Both directions share the same WebSocket channel address.
55
# Callers correlate requests and responses using the JSON-RPC `id` field.
66
#
77
# 7 methods: restartExpectation, restartAllExpectations, abortExpectation,
88
# restartPackageContainer, troubleshoot, getExpectationManagerStatus,
99
# debugKillApp
1010

11-
rpcCoreTopm:
12-
address: rpc/core-to-pm
13-
title: RPC Channel — Core to Package Manager
11+
rpcConsumerToPm:
12+
address: rpc/consumer-to-pm
13+
title: RPC Channel — Consumer to Package Manager
1414
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.
15+
Bidirectional JSON-RPC 2.0 channel where the consumer is the caller.
16+
The consumer sends Request objects; the Package Manager sends Response objects.
1717
Both message types share this channel; the JSON-RPC `id` field correlates them.
1818
messages:
1919
# Requests (Core → PM)
@@ -31,7 +31,7 @@ rpcCoreTopm:
3131
$ref: '../components/messages/rpc-messages.yaml#/GetExpectationManagerStatusRequest'
3232
DebugKillAppRequest:
3333
$ref: '../components/messages/rpc-messages.yaml#/DebugKillAppRequest'
34-
# Responses (PM → Core)
34+
# Responses (PM → Consumer)
3535
RestartExpectationResponse:
3636
$ref: '../components/messages/rpc-messages.yaml#/RestartExpectationResponse'
3737
RestartAllExpectationsResponse:

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# RPC channel: Package Manager → Core.
1+
# RPC channel: Package Manager → Consumer.
22
#
3-
# PM sends JSON-RPC 2.0 Requests; Core sends JSON-RPC 2.0 Responses.
3+
# PM sends JSON-RPC 2.0 Requests; the consumer sends JSON-RPC 2.0 Responses.
44
# Both directions share the same WebSocket channel address.
55
# Callers correlate requests and responses using the JSON-RPC `id` field.
66
#
77
# 1 method: fetchPackageInfoMetadata
88

9-
rpcPmToCore:
10-
address: rpc/pm-to-core
11-
title: RPC Channel — Package Manager to Core
9+
rpcPmToConsumer:
10+
address: rpc/pm-to-consumer
11+
title: RPC Channel — Package Manager to Consumer
1212
description: >
1313
Bidirectional JSON-RPC 2.0 channel where the Package Manager is the caller.
14-
PM sends Request objects; Sofie Core sends Response objects.
14+
PM sends Request objects; the consumer sends Response objects.
1515
Both message types share this channel; the JSON-RPC `id` field correlates them.
1616
messages:
17-
# Request (PM → Core)
17+
# Request (PM → Consumer)
1818
FetchPackageInfoMetadataRequest:
1919
$ref: '../components/messages/rpc-messages.yaml#/FetchPackageInfoMetadataRequest'
2020
# Response (Core → PM)

apps/package-manager-api/asyncapi/components/messages/from-core-messages.yaml renamed to apps/package-manager-api/asyncapi/components/messages/from-consumer-messages.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Messages sent FROM Sofie Core TO the Package Manager.
1+
# Messages sent FROM the consumer TO the Package Manager.
22
# Two channels: expectations and packageContainers.
33
# All use CRUD-delta events (added / updated / removed).
44

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Messages sent FROM the Package Manager TO Sofie Core.
1+
# Messages sent FROM the Package Manager TO the consumer.
22
#
33
# Three event channels (CRUD deltas) plus two event channels for package-info:
44
# - workStatuses (ExpectationStatus CRUD, keyed by ExpectationId)
@@ -7,7 +7,7 @@
77
# - packageInfo (PackageInfo update/remove — fire and forget)
88
#
99
# There is no ExpectedPackageId anywhere in these messages.
10-
# Core maps ExpectationId back to its own expected packages internally.
10+
# The consumer maps ExpectationId back to its own expected packages internally.
1111

1212
# ---------------------------------------------------------------------------
1313
# workStatuses channel messages
@@ -159,7 +159,7 @@ PackageInfoUpdated:
159159
title: Package Info Updated
160160
summary: >
161161
A Worker has completed a scan or probe operation and the result should be
162-
stored in Core's package-info collection. Keyed by ExpectationId.
162+
stored in the consumer's package-info collection. Keyed by ExpectationId.
163163
This is a fire-and-forget event; no acknowledgement is returned.
164164
contentType: application/json
165165
payload:
@@ -170,7 +170,7 @@ PackageInfoRemoved:
170170
title: Package Info Removed
171171
summary: >
172172
Previously stored package-info for an Expectation should be deleted.
173-
An optional removeDelay instructs Core to delay the deletion.
173+
An optional removeDelay instructs the consumer to delay the deletion.
174174
This is a fire-and-forget event; no acknowledgement is returned.
175175
contentType: application/json
176176
payload:

0 commit comments

Comments
 (0)