@fonoster/apiserver 0.30.0 → 0.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/dist/applications/buildService.d.ts +1 -1
  2. package/dist/applications/buildService.js +4 -3
  3. package/dist/applications/createCreateApplication.js +6 -3
  4. package/dist/applications/createCreateTestToken.d.ts +3 -1
  5. package/dist/applications/createCreateTestToken.js +18 -13
  6. package/dist/applications/createGetFnUtil.d.ts +1 -1
  7. package/dist/applications/createUpdateApplication.js +6 -4
  8. package/dist/applications/evalKeys.d.ts +7 -1
  9. package/dist/applications/evalKeys.js +9 -3
  10. package/dist/applications/session/appModel.d.ts +28 -4
  11. package/dist/applications/session/appModel.js +74 -35
  12. package/dist/billing/buildService.d.ts +24 -0
  13. package/dist/billing/buildService.js +116 -0
  14. package/dist/{migration/cli.js → bin/usage.js} +46 -22
  15. package/dist/calls/buildService.d.ts +1 -20
  16. package/dist/calls/buildService.js +50 -10
  17. package/dist/calls/createCall.d.ts +16 -2
  18. package/dist/calls/createCall.js +29 -6
  19. package/dist/calls/createCallPublisher.d.ts +6 -4
  20. package/dist/calls/createCallPublisher.js +6 -5
  21. package/dist/calls/createTrackCall.d.ts +16 -13
  22. package/dist/calls/createTrackCall.js +78 -55
  23. package/dist/calls/getCall.d.ts +3 -3
  24. package/dist/calls/getCall.js +2 -3
  25. package/dist/calls/listCalls.d.ts +4 -4
  26. package/dist/calls/listCalls.js +2 -3
  27. package/dist/calls/types.d.ts +2 -1
  28. package/dist/capabilities/createGetCapabilities.d.ts +3 -0
  29. package/dist/capabilities/createGetCapabilities.js +2 -1
  30. package/dist/config/index.js +1 -3
  31. package/dist/config/schema.d.ts +106 -102
  32. package/dist/config/schema.js +39 -47
  33. package/dist/core/applyCatalog.d.ts +3 -3
  34. package/dist/core/applyCatalog.js +5 -4
  35. package/dist/core/regionHooks.d.ts +1 -0
  36. package/dist/core/runServices.js +25 -4
  37. package/dist/core/services.d.ts +25 -1
  38. package/dist/core/services.js +35 -11
  39. package/dist/core/testTokenConfig.js +2 -2
  40. package/dist/core/upsertRoomrPeer.d.ts +6 -0
  41. package/dist/core/{upsertMediaNodePeer.js → upsertRoomrPeer.js} +9 -9
  42. package/dist/envs.d.ts +30 -16
  43. package/dist/envs.js +49 -31
  44. package/dist/index.js +23 -22
  45. package/dist/outbound/createNodeDirectory.d.ts +35 -13
  46. package/dist/outbound/createNodeDirectory.js +54 -20
  47. package/dist/outbound/index.d.ts +1 -0
  48. package/dist/outbound/index.js +1 -0
  49. package/dist/outbound/placeOutboundCall.d.ts +53 -13
  50. package/dist/outbound/placeOutboundCall.js +135 -88
  51. package/dist/outbound/placementSweep.d.ts +56 -0
  52. package/dist/outbound/placementSweep.js +127 -0
  53. package/dist/outbound/runOutboundCalls.d.ts +18 -14
  54. package/dist/outbound/runOutboundCalls.js +46 -34
  55. package/dist/providers/createProvidersHandlers.d.ts +1 -10
  56. package/dist/providers/createProvidersHandlers.js +20 -25
  57. package/dist/providers/index.d.ts +2 -2
  58. package/dist/providers/index.js +2 -2
  59. package/dist/providers/registryUsage.d.ts +2 -2
  60. package/dist/providers/registryUsage.js +5 -5
  61. package/dist/records/createIndexRecord.d.ts +26 -3
  62. package/dist/records/createIndexRecord.js +37 -10
  63. package/dist/records/createRecordsRouter.js +4 -2
  64. package/dist/records/createSearchRecords.d.ts +4 -3
  65. package/dist/records/createSearchRecords.js +9 -21
  66. package/dist/records/maintenance.d.ts +1 -1
  67. package/dist/records/maintenance.js +1 -1
  68. package/dist/records/runCallRecords.d.ts +2 -0
  69. package/dist/records/runCallRecords.js +1 -1
  70. package/dist/records/types.d.ts +2 -0
  71. package/dist/regions/configSync.d.ts +5 -5
  72. package/dist/regions/configSync.js +9 -9
  73. package/dist/regions/createRegionsRouter.d.ts +6 -6
  74. package/dist/regions/createRegionsRouter.js +5 -5
  75. package/dist/regions/link.js +1 -1
  76. package/dist/regions/runRegions.d.ts +2 -0
  77. package/dist/regions/runRegions.js +4 -0
  78. package/dist/regions/service.js +4 -4
  79. package/dist/regions/sources.d.ts +1 -1
  80. package/dist/regions/sources.js +4 -4
  81. package/dist/regions/status.js +5 -4
  82. package/dist/regions/types.d.ts +2 -2
  83. package/dist/usage/buildService.d.ts +16 -0
  84. package/dist/{calls/influxdb.js → usage/buildService.js} +16 -9
  85. package/dist/{events/createPerCallCache.d.ts → usage/createGetUsage.d.ts} +7 -7
  86. package/dist/usage/createGetUsage.js +118 -0
  87. package/dist/usage/ingestUsage.d.ts +7 -0
  88. package/dist/usage/ingestUsage.js +87 -0
  89. package/dist/usage/publishRecordedUsage.d.ts +52 -0
  90. package/dist/usage/publishRecordedUsage.js +103 -0
  91. package/dist/usage/publishUsage.d.ts +29 -0
  92. package/dist/usage/publishUsage.js +50 -0
  93. package/dist/usage/rebuildUsage.d.ts +48 -0
  94. package/dist/usage/rebuildUsage.js +104 -0
  95. package/dist/usage/runUsageConsumer.d.ts +22 -0
  96. package/dist/usage/runUsageConsumer.js +78 -0
  97. package/dist/usage/snapshotStorage.d.ts +14 -0
  98. package/dist/usage/snapshotStorage.js +95 -0
  99. package/dist/usage/types.d.ts +36 -0
  100. package/dist/voice/stt/types.js +1 -1
  101. package/dist/webhooks/lostCalls.d.ts +35 -12
  102. package/dist/webhooks/lostCalls.js +86 -48
  103. package/dist/webhooks/nodeCallEvents.d.ts +73 -0
  104. package/dist/webhooks/nodeCallEvents.js +177 -0
  105. package/dist/webhooks/runWebhookFanout.d.ts +10 -4
  106. package/dist/webhooks/runWebhookFanout.js +41 -39
  107. package/package.json +17 -19
  108. package/dist/applications/migration/PrismaApplicationStore.d.ts +0 -55
  109. package/dist/applications/migration/PrismaApplicationStore.js +0 -92
  110. package/dist/applications/migration/convertLegacyApplication.d.ts +0 -11
  111. package/dist/applications/migration/convertLegacyApplication.js +0 -112
  112. package/dist/applications/migration/index.d.ts +0 -22
  113. package/dist/applications/migration/index.js +0 -38
  114. package/dist/applications/migration/migrateApplications.d.ts +0 -43
  115. package/dist/applications/migration/migrateApplications.js +0 -87
  116. package/dist/applications/migration/types.d.ts +0 -92
  117. package/dist/applications/migration/types.js +0 -20
  118. package/dist/calls/createFetchCalls.d.ts +0 -22
  119. package/dist/calls/createFetchCalls.js +0 -88
  120. package/dist/calls/createFetchSingleCall.d.ts +0 -22
  121. package/dist/calls/createFetchSingleCall.js +0 -54
  122. package/dist/calls/influxdb.d.ts +0 -2
  123. package/dist/core/upsertMediaNodePeer.d.ts +0 -6
  124. package/dist/events/callRefs.d.ts +0 -29
  125. package/dist/events/callRefs.js +0 -103
  126. package/dist/events/createCdrWriter.d.ts +0 -25
  127. package/dist/events/createCdrWriter.js +0 -95
  128. package/dist/events/createInfluxDbPub.d.ts +0 -10
  129. package/dist/events/createInfluxDbPub.js +0 -46
  130. package/dist/events/createPerCallCache.js +0 -46
  131. package/dist/events/mapCallDirectionToEnum.d.ts +0 -21
  132. package/dist/events/mapCallDirectionToEnum.js +0 -37
  133. package/dist/events/nats.d.ts +0 -44
  134. package/dist/events/nats.js +0 -93
  135. package/dist/events/transformEvent.d.ts +0 -4
  136. package/dist/events/transformEvent.js +0 -87
  137. package/dist/events/types.d.ts +0 -26
  138. package/dist/migration/argv.d.ts +0 -22
  139. package/dist/migration/argv.js +0 -42
  140. package/dist/migration/catalogMapping.d.ts +0 -30
  141. package/dist/migration/catalogMapping.js +0 -53
  142. package/dist/migration/index.d.ts +0 -27
  143. package/dist/migration/index.js +0 -43
  144. package/dist/migration/migrateAssistants.d.ts +0 -8
  145. package/dist/migration/migrateAssistants.js +0 -169
  146. package/dist/migration/migrateCredentials.d.ts +0 -4
  147. package/dist/migration/migrateCredentials.js +0 -107
  148. package/dist/migration/migrateIntegrations.d.ts +0 -32
  149. package/dist/migration/migrateIntegrations.js +0 -136
  150. package/dist/migration/migrateLegacy.d.ts +0 -41
  151. package/dist/migration/migrateLegacy.js +0 -76
  152. package/dist/migration/providerKeys.d.ts +0 -14
  153. package/dist/migration/providerKeys.js +0 -61
  154. package/dist/migration/seedCatalog.d.ts +0 -2
  155. package/dist/migration/seedCatalog.js +0 -160
  156. package/dist/migration/types.d.ts +0 -42
  157. package/dist/migration/types.js +0 -31
  158. /package/dist/{migration/cli.d.ts → bin/usage.d.ts} +0 -0
  159. /package/dist/{events → usage}/types.js +0 -0
@@ -9,17 +9,40 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
9
9
  });
10
10
  };
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.PlacementError = exports.NO_CAPACITY = exports.MAX_PLACEMENT_ATTEMPTS = exports.GATEWAY_OUTBOUND_SUBJECT = void 0;
12
+ exports.PlacementError = exports.NO_CAPACITY = exports.SAME_NODE_ATTEMPTS = exports.MAX_PLACEMENT_ATTEMPTS = void 0;
13
+ exports.calleeUri = calleeUri;
14
+ exports.outboundMetadata = outboundMetadata;
15
+ exports.createCallRequest = createCallRequest;
13
16
  exports.placeOutboundCall = placeOutboundCall;
14
- /** The gateway subject that opens the app session when the callee answers (gateway B8). */
15
- exports.GATEWAY_OUTBOUND_SUBJECT = "gateway.outbound";
16
- const REPLY_TIMEOUT_MS = 2000;
17
+ /**
18
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
19
+ * http://github.com/fonoster/fonoster
20
+ *
21
+ * This file is part of Fonoster
22
+ *
23
+ * Licensed under the MIT License (the "License");
24
+ * you may not use this file except in compliance with
25
+ * the License. You may obtain a copy of the License at
26
+ *
27
+ * https://opensource.org/licenses/MIT
28
+ *
29
+ * Unless required by applicable law or agreed to in writing, software
30
+ * distributed under the License is distributed on an "AS IS" BASIS,
31
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
32
+ * See the License for the specific language governing permissions and
33
+ * limitations under the License.
34
+ */
35
+ const common_1 = require("@fonoster/common");
36
+ const grpc_js_1 = require("@grpc/grpc-js");
17
37
  /** Nodes tried for one call before it fails with no_capacity. */
18
38
  exports.MAX_PLACEMENT_ATTEMPTS = 3;
39
+ /**
40
+ * Attempts of CreateCall on the same node when the outcome is unknown (a timeout or a connection
41
+ * lost after sending): the same call_ref and parameters, so the node dedupes it.
42
+ */
43
+ exports.SAME_NODE_ATTEMPTS = 3;
19
44
  /** The PlacementError code for "no node took the call" (CreateCall's RESOURCE_EXHAUSTED). */
20
45
  exports.NO_CAPACITY = "no_capacity";
21
- /** room.create refusals that send the call to the next node. */
22
- const TRY_NEXT = new Set(["at_capacity", "draining"]);
23
46
  class PlacementError extends Error {
24
47
  constructor(code, message) {
25
48
  super(message);
@@ -29,97 +52,121 @@ class PlacementError extends Error {
29
52
  }
30
53
  exports.PlacementError = PlacementError;
31
54
  /**
32
- * Places an API-originated call (CreateCall) on the media nodes, replacing Asterisk's originate:
33
- * `room.create` on the least-loaded eligible node (the next one, up to MAX_PLACEMENT_ATTEMPTS
34
- * nodes, when a node is full, draining or silent), `gateway.outbound` so a gateway opens the app
35
- * session on `call.answered`, then `participant.dial` through Routr with the headers Routr
36
- * routes API-originated calls by (X-Dod-Number picks the trunk). The room carries the call's
37
- * ref, so the node also publishes the call's status events on `calls.<ref>.events` (TrackCall).
55
+ * A node's refusal that sends the call to another node (control-plane "Call creation picks the
56
+ * least-loaded Roomr node"): the node is full (RESOURCE_EXHAUSTED) or not there (UNAVAILABLE).
38
57
  */
39
- function placeOutboundCall(request_1, nodes_1, call_1) {
40
- return __awaiter(this, arguments, void 0, function* (request, nodes, call, hooks = {}) {
41
- var _a, _b, _c, _d, _e;
42
- const command = (nodeId, body) => __awaiter(this, void 0, void 0, function* () {
43
- var _a, _b;
44
- const reply = yield request(`media.${nodeId}.commands`, body, REPLY_TIMEOUT_MS);
45
- if (reply.type !== "ack") {
46
- throw new PlacementError(String((_a = reply.code) !== null && _a !== void 0 ? _a : "error"), `${body.type} failed on ${nodeId}: ${(_b = reply.code) !== null && _b !== void 0 ? _b : "error"}`);
58
+ const isRefusal = (e) => e instanceof common_1.Roomr.RoomrError &&
59
+ (e.code === grpc_js_1.status.RESOURCE_EXHAUSTED || e.code === grpc_js_1.status.UNAVAILABLE);
60
+ /** An outcome the caller cannot know (the request may have been served): retry the same node. */
61
+ const isAmbiguous = (e) => !(e instanceof common_1.Roomr.RoomrError) ||
62
+ e.code === grpc_js_1.status.DEADLINE_EXCEEDED ||
63
+ e.code === grpc_js_1.status.CANCELLED ||
64
+ e.code === grpc_js_1.status.UNKNOWN;
65
+ /** The PlacementError for a failed RPC: the API maps these codes to its own status codes. */
66
+ function placementError(what, nodeId, e) {
67
+ var _a;
68
+ const code = e instanceof common_1.Roomr.RoomrError
69
+ ? ((_a = {
70
+ [grpc_js_1.status.RESOURCE_EXHAUSTED]: exports.NO_CAPACITY,
71
+ [grpc_js_1.status.INVALID_ARGUMENT]: "invalid_argument",
72
+ [grpc_js_1.status.ALREADY_EXISTS]: "already_exists"
73
+ }[e.code]) !== null && _a !== void 0 ? _a : "unavailable")
74
+ : "unavailable";
75
+ return new PlacementError(code, `${what} failed on ${nodeId}: ${e.message}`);
76
+ }
77
+ /** Runs `rpc`, again on the same node while its outcome is ambiguous. */
78
+ function sameNode(rpc) {
79
+ return __awaiter(this, void 0, void 0, function* () {
80
+ for (let attempt = 1;; attempt++) {
81
+ try {
82
+ return yield rpc();
47
83
  }
48
- return reply;
49
- });
50
- // room.create on the least-loaded eligible node; a full, draining or silent node sends the
51
- // call to the next one.
84
+ catch (e) {
85
+ if (attempt >= exports.SAME_NODE_ATTEMPTS || !isAmbiguous(e))
86
+ throw e;
87
+ }
88
+ }
89
+ });
90
+ }
91
+ /** The Request-URI for a callee: a SIP URI as given, a number at the proxy's host. */
92
+ function calleeUri(to, proxy) {
93
+ if (/^sips?:/i.test(to))
94
+ return to;
95
+ const host = proxy.replace(/:\d+$/, "");
96
+ return `sip:${to}@${host}`;
97
+ }
98
+ /** The Roomr `metadata` of an API-originated call (AppBridge reads it at answer, 4.8). */
99
+ function outboundMetadata(call) {
100
+ return Object.assign({ app_ref: call.appRef, from: call.from, to: call.to }, (call.metadata && Object.keys(call.metadata).length
101
+ ? { app_metadata: JSON.stringify(call.metadata) }
102
+ : {}));
103
+ }
104
+ /**
105
+ * The CreateCall request for an API-originated call: dialed through the SIP proxy with the
106
+ * pass-through headers it routes on (`X-DOD-Number`, the caller id, picks the trunk; From is the
107
+ * node's own identity), `to.auth` for the proxy's challenge, and the app in `metadata.app_ref`.
108
+ */
109
+ function createCallRequest(call, outbound) {
110
+ return Object.assign(Object.assign({ callRef: call.ref, to: Object.assign({ uri: calleeUri(call.to, outbound.proxy), proxy: outbound.proxy, headers: {
111
+ "X-DOD-Number": call.from,
112
+ "X-Call-Ref": call.ref,
113
+ "X-Access-Key-Id": call.accessKeyId,
114
+ "X-Is-Api-Originated-Type": "true"
115
+ } }, (outbound.auth ? { auth: outbound.auth } : {})) }, (call.timeout ? { ringTimeoutS: call.timeout } : {})), { metadata: outboundMetadata(call) });
116
+ }
117
+ /**
118
+ * Places an API-originated call (CreateCall) on a Roomr node over gRPC, at the heartbeat's
119
+ * `control_addr` (control-plane "Call creation picks the least-loaded Roomr node"):
120
+ *
121
+ * - `CreateCall` with the call's ref on the highest-scoring eligible node. The node dials the
122
+ * callee, creates the room on answer and opens the call's control stream to AppBridge, which
123
+ * finds the app in `metadata.app_ref`; a busy, unanswered or rejected call creates no room and
124
+ * ends with the node's `call.ended` (the control plane's minimal record and call.failed).
125
+ * - `RESOURCE_EXHAUSTED` or `UNAVAILABLE` sends the call to the next node, up to
126
+ * MAX_PLACEMENT_ATTEMPTS nodes, then `no_capacity` (synchronously: the API caller gets it).
127
+ * - A timeout or a lost connection is ambiguous (the INVITE may be out): CreateCall is repeated on
128
+ * the same node with the same call_ref and parameters (the node dedupes it), never on another;
129
+ * still no answer after SAME_NODE_ATTEMPTS fails the call, and EndCall is sent in case the node
130
+ * did take it.
131
+ *
132
+ * `onAttempt` is told each node before anything is sent to it (the session registry's
133
+ * `placements.<callRef>` entry, written before the RPC so a sweep can end the call if this
134
+ * replica dies mid-placement).
135
+ */
136
+ function placeOutboundCall(deps_1, call_1) {
137
+ return __awaiter(this, arguments, void 0, function* (deps, call, hooks = {}) {
138
+ var _a;
139
+ const { roomr, nodes } = deps;
140
+ const request = createCallRequest(call, deps.outbound);
52
141
  const tried = new Set();
53
- let placedOn;
54
- while (!placedOn && tried.size < exports.MAX_PLACEMENT_ATTEMPTS) {
55
- const candidate = nodes.pick(tried);
56
- if (!candidate)
142
+ while (tried.size < exports.MAX_PLACEMENT_ATTEMPTS) {
143
+ const nodeId = nodes.pick(tried, call.region);
144
+ if (!nodeId)
57
145
  break;
58
- tried.add(candidate);
146
+ tried.add(nodeId);
147
+ const addr = nodes.addressOf(nodeId);
148
+ yield ((_a = hooks.onAttempt) === null || _a === void 0 ? void 0 : _a.call(hooks, nodeId, addr));
59
149
  try {
60
- const room = yield command(candidate, {
61
- type: "room.create",
62
- id: `${call.ref}:room`,
63
- callRef: call.ref
64
- });
65
- placedOn = { nodeId: candidate, roomRef: String((_a = room.roomRef) !== null && _a !== void 0 ? _a : "") };
150
+ const placed = yield sameNode(() => roomr.createCall(addr, request));
151
+ nodes.placed(nodeId);
152
+ return { nodeId, roomRef: placed.roomRef, callRef: placed.callRef };
66
153
  }
67
154
  catch (e) {
68
- if (e instanceof PlacementError) {
69
- if (!TRY_NEXT.has(e.code))
70
- throw e;
71
- nodes.refused(candidate, e.code);
155
+ if (isRefusal(e)) {
156
+ nodes.refused(nodeId, e.code === grpc_js_1.status.UNAVAILABLE
157
+ ? "unavailable"
158
+ : "at_capacity");
159
+ continue;
72
160
  }
73
- // Otherwise no reply in time: the node is gone or stuck; try the next one.
161
+ // Anything else fails the call: only a refusal says the node did nothing. After an
162
+ // ambiguous outcome the node may hold the call; end it (the API caller gets an error).
163
+ if (isAmbiguous(e))
164
+ yield roomr.endCall(addr, { callRef: call.ref }).catch(() => undefined);
165
+ throw placementError("CreateCall", nodeId, e);
74
166
  }
75
167
  }
76
- if (!placedOn) {
77
- throw new PlacementError(exports.NO_CAPACITY, tried.size === 0
78
- ? "no media node has room for the call"
79
- : `no media node took the call (tried ${[...tried].join(", ")})`);
80
- }
81
- const { nodeId, roomRef } = placedOn;
82
- nodes.placed(nodeId);
83
- (_b = hooks.onRoom) === null || _b === void 0 ? void 0 : _b.call(hooks, nodeId, roomRef);
84
- const endRoom = () => command(nodeId, {
85
- type: "room.end",
86
- id: `${call.ref}:end`,
87
- roomRef
88
- }).catch(() => undefined);
89
- let claimed;
90
- try {
91
- claimed = yield request(exports.GATEWAY_OUTBOUND_SUBJECT, {
92
- nodeId,
93
- roomRef,
94
- appRef: call.appRef,
95
- callRef: call.ref,
96
- from: call.from,
97
- to: call.to,
98
- metadata: (_c = call.metadata) !== null && _c !== void 0 ? _c : {}
99
- }, REPLY_TIMEOUT_MS);
100
- }
101
- catch (e) {
102
- yield endRoom();
103
- throw new PlacementError("no_gateway", `no gateway took the call: ${e.message}`);
104
- }
105
- if (claimed.type !== "ack") {
106
- yield endRoom();
107
- throw new PlacementError(String((_d = claimed.code) !== null && _d !== void 0 ? _d : "error"), `the gateway refused the call: ${(_e = claimed.code) !== null && _e !== void 0 ? _e : "error"}`);
108
- }
109
- try {
110
- yield command(nodeId, Object.assign(Object.assign({ type: "participant.dial", id: `${call.ref}:dial`, roomRef, to: call.to, from: call.from, timeout: call.timeout }, (typeof claimed.gatewayRef === "string"
111
- ? { gatewayRef: claimed.gatewayRef }
112
- : {})), { headers: {
113
- "X-Call-Ref": call.ref,
114
- "X-Dod-Number": call.from,
115
- "X-Access-Key-Id": call.accessKeyId,
116
- "X-Is-Api-Originated-Type": "true"
117
- } }));
118
- }
119
- catch (e) {
120
- yield endRoom();
121
- throw e;
122
- }
123
- return { nodeId, roomRef };
168
+ throw new PlacementError(exports.NO_CAPACITY, tried.size === 0
169
+ ? "no Roomr node has room for the call"
170
+ : `no Roomr node took the call (tried ${[...tried].join(", ")})`);
124
171
  });
125
172
  }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
3
+ * http://github.com/fonoster/fonoster
4
+ *
5
+ * This file is part of Fonoster
6
+ *
7
+ * Licensed under the MIT License (the "License");
8
+ * you may not use this file except in compliance with
9
+ * the License. You may obtain a copy of the License at
10
+ *
11
+ * https://opensource.org/licenses/MIT
12
+ *
13
+ * Unless required by applicable law or agreed to in writing, software
14
+ * distributed under the License is distributed on an "AS IS" BASIS,
15
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ * See the License for the specific language governing permissions and
17
+ * limitations under the License.
18
+ */
19
+ import { Roomr } from "@fonoster/common";
20
+ import type { KV } from "nats";
21
+ /**
22
+ * A placement entry older than this was left by a replica that died mid-placement: every step of
23
+ * a placement rewrites its entry well within it (CreateCall and its retries on one node).
24
+ */
25
+ export declare const PLACEMENT_STALE_MS = 10000;
26
+ /**
27
+ * Placements in the session registry (control-plane "Outbound calls are registered before they
28
+ * are placed"): before CreateCall reaches a node, the placing replica writes
29
+ * `placements.<callRef>` = { callRef, nodeRef, controlAddr }, rewrites it when it moves to
30
+ * another node, and deletes it once CreateCall has answered (or the placement failed). Every
31
+ * replica follows the entries; one that sits unchanged for `staleMs` belongs to a replica that
32
+ * died mid-placement (its API caller got no answer, so the call must not go on). The sweep
33
+ * removes it, and reports the call FAILED (`failed`), when its node is down (no fresh heartbeat,
34
+ * or `node.down`) or answers `NOT_FOUND` for the call; a call the node does hold is ended
35
+ * (EndCall; its `call.ended` then follows on `roomr.events.<call_ref>`). Registry writes are best
36
+ * effort and never fail a placement. Nothing is replayed: a placement whose events were lost is
37
+ * closed by this sweep or by TrackCall's own node-down and maximum-duration sweeps.
38
+ */
39
+ export declare function createPlacementSweep(deps: {
40
+ kv: KV;
41
+ roomr: Roomr.RoomrCalls;
42
+ /** Whether the node is live (fresh heartbeat); a down node's placements fail at once. */
43
+ nodeUp?: (nodeRef: string) => boolean;
44
+ /** The call never got placed: its record ends FAILED (TrackCall). */
45
+ failed?: (callRef: string) => unknown;
46
+ staleMs?: number;
47
+ now?: () => number;
48
+ }): Promise<{
49
+ /** Writes (or rewrites) the call's entry before CreateCall reaches `nodeRef`. */
50
+ placing(callRef: string, nodeRef: string, controlAddr: string): Promise<void>;
51
+ /** The placement is over (placed or failed): its entry goes. */
52
+ placed(callRef: string): Promise<void>;
53
+ /** Ends the calls of stale entries now (tests; the timer runs it too). */
54
+ sweep: () => Promise<string[]>;
55
+ stop(): void;
56
+ }>;
@@ -0,0 +1,127 @@
1
+ "use strict";
2
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
+ return new (P || (P = Promise))(function (resolve, reject) {
5
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
9
+ });
10
+ };
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.PLACEMENT_STALE_MS = void 0;
13
+ exports.createPlacementSweep = createPlacementSweep;
14
+ /**
15
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
16
+ * http://github.com/fonoster/fonoster
17
+ *
18
+ * This file is part of Fonoster
19
+ *
20
+ * Licensed under the MIT License (the "License");
21
+ * you may not use this file except in compliance with
22
+ * the License. You may obtain a copy of the License at
23
+ *
24
+ * https://opensource.org/licenses/MIT
25
+ *
26
+ * Unless required by applicable law or agreed to in writing, software
27
+ * distributed under the License is distributed on an "AS IS" BASIS,
28
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29
+ * See the License for the specific language governing permissions and
30
+ * limitations under the License.
31
+ */
32
+ const common_1 = require("@fonoster/common");
33
+ const logger_1 = require("@fonoster/logger");
34
+ const grpc_js_1 = require("@grpc/grpc-js");
35
+ const logger = (0, logger_1.getLogger)({ service: "apiserver", filePath: __filename });
36
+ /**
37
+ * A placement entry older than this was left by a replica that died mid-placement: every step of
38
+ * a placement rewrites its entry well within it (CreateCall and its retries on one node).
39
+ */
40
+ exports.PLACEMENT_STALE_MS = 10000;
41
+ /** How often each replica looks for stale placements. */
42
+ const SWEEP_EVERY_MS = 2000;
43
+ /**
44
+ * Placements in the session registry (control-plane "Outbound calls are registered before they
45
+ * are placed"): before CreateCall reaches a node, the placing replica writes
46
+ * `placements.<callRef>` = { callRef, nodeRef, controlAddr }, rewrites it when it moves to
47
+ * another node, and deletes it once CreateCall has answered (or the placement failed). Every
48
+ * replica follows the entries; one that sits unchanged for `staleMs` belongs to a replica that
49
+ * died mid-placement (its API caller got no answer, so the call must not go on). The sweep
50
+ * removes it, and reports the call FAILED (`failed`), when its node is down (no fresh heartbeat,
51
+ * or `node.down`) or answers `NOT_FOUND` for the call; a call the node does hold is ended
52
+ * (EndCall; its `call.ended` then follows on `roomr.events.<call_ref>`). Registry writes are best
53
+ * effort and never fail a placement. Nothing is replayed: a placement whose events were lost is
54
+ * closed by this sweep or by TrackCall's own node-down and maximum-duration sweeps.
55
+ */
56
+ function createPlacementSweep(deps) {
57
+ return __awaiter(this, void 0, void 0, function* () {
58
+ var _a, _b, _c;
59
+ const staleMs = (_a = deps.staleMs) !== null && _a !== void 0 ? _a : exports.PLACEMENT_STALE_MS;
60
+ const now = (_b = deps.now) !== null && _b !== void 0 ? _b : Date.now;
61
+ const seen = new Map();
62
+ const key = (ref) => common_1.Sessions.sessionKey("placements", ref);
63
+ const write = (ref, value) => __awaiter(this, void 0, void 0, function* () {
64
+ try {
65
+ if (value)
66
+ yield deps.kv.put(key(ref), JSON.stringify(value));
67
+ else
68
+ yield deps.kv.delete(key(ref));
69
+ }
70
+ catch (e) {
71
+ logger.warn(`placement entry ${ref} not written: ${e.message}`);
72
+ }
73
+ });
74
+ const stopWatch = yield common_1.Sessions.watchSessions(deps.kv, "placements", (e) => {
75
+ if (e.value)
76
+ seen.set(e.id, { value: e.value, seenAt: now() });
77
+ else
78
+ seen.delete(e.id);
79
+ });
80
+ const sweep = () => __awaiter(this, void 0, void 0, function* () {
81
+ var _a, _b, _c, _d, _e;
82
+ const at = now();
83
+ const ended = [];
84
+ for (const [id, p] of [...seen]) {
85
+ if (at - p.seenAt <= staleMs)
86
+ continue;
87
+ seen.delete(id);
88
+ const callRef = String((_a = p.value.callRef) !== null && _a !== void 0 ? _a : id);
89
+ const addr = String((_b = p.value.controlAddr) !== null && _b !== void 0 ? _b : "");
90
+ const nodeRef = String((_c = p.value.nodeRef) !== null && _c !== void 0 ? _c : "");
91
+ logger.warn(`outbound call ${callRef} was left mid-placement on ${nodeRef}; sweeping it`);
92
+ let notFound = !addr || ((_d = deps.nodeUp) === null || _d === void 0 ? void 0 : _d.call(deps, nodeRef)) === false;
93
+ if (!notFound) {
94
+ notFound = yield deps.roomr.endCall(addr, { callRef }).then(() => false, (e) => e instanceof common_1.Roomr.RoomrError && e.code === grpc_js_1.status.NOT_FOUND);
95
+ }
96
+ if (notFound)
97
+ yield ((_e = deps.failed) === null || _e === void 0 ? void 0 : _e.call(deps, callRef));
98
+ yield write(id);
99
+ ended.push(callRef);
100
+ }
101
+ return ended;
102
+ });
103
+ const timer = setInterval(() => void sweep(), SWEEP_EVERY_MS);
104
+ (_c = timer.unref) === null || _c === void 0 ? void 0 : _c.call(timer);
105
+ return {
106
+ /** Writes (or rewrites) the call's entry before CreateCall reaches `nodeRef`. */
107
+ placing(callRef, nodeRef, controlAddr) {
108
+ return write(callRef, {
109
+ callRef,
110
+ nodeRef,
111
+ controlAddr,
112
+ at: new Date().toISOString()
113
+ });
114
+ },
115
+ /** The placement is over (placed or failed): its entry goes. */
116
+ placed(callRef) {
117
+ return write(callRef);
118
+ },
119
+ /** Ends the calls of stale entries now (tests; the timer runs it too). */
120
+ sweep,
121
+ stop() {
122
+ clearInterval(timer);
123
+ stopWatch();
124
+ }
125
+ };
126
+ });
127
+ }
@@ -16,33 +16,37 @@
16
16
  * See the License for the specific language governing permissions and
17
17
  * limitations under the License.
18
18
  */
19
- import { NatsTarget } from "@fonoster/common";
19
+ import { NatsTarget, Roomr } from "@fonoster/common";
20
20
  import { NatsConnection } from "nats";
21
- import { Requester } from "./placeOutboundCall";
22
- /** JSON request and reply over a NATS connection. */
23
- export declare function natsRequester(nc: NatsConnection): Requester;
21
+ import { OutboundTarget } from "./placeOutboundCall";
24
22
  /**
25
23
  * The control plane's part of a call's status events for TrackCall: TRYING when placement starts,
26
- * `{ref, nodeId}` once a node holds the call's room (TrackCall then follows that node's
27
- * heartbeats), and FAILED when placement fails. Everything after the room exists (PROGRESS, ANSWER, BUSY, the final
28
- * room.ended) comes from the media node on the same per-call subject, so the statuses keep
29
- * flowing to every replica's TrackCall even if this replica dies.
24
+ * `{ref, node_ref}` once a node took CreateCall (TrackCall then follows that node's heartbeats), and FAILED when placement fails. Everything after that (call.ringing,
25
+ * call.answered, call.ended) comes from the Roomr node on `roomr.events.<ref>`, so the statuses
26
+ * keep flowing to every replica's TrackCall even if this replica dies.
30
27
  */
31
28
  export declare function callTracker(nc: NatsConnection, ref: string): {
32
29
  placed(nodeId: string): void;
33
30
  failed(): void;
34
31
  };
35
32
  /**
36
- * Serves `calls.create` (a request from CreateCall) by placing each call on the media nodes.
37
- * Takes over from the Asterisk originate the apiserver used before the rebuild (cleanbreak
38
- * CB-B2). The reply comes as soon as a node has accepted the call's room (`{type: "ack", ref,
39
- * nodeId}`), or with `{type: "error", code, message}` when no node took it (`no_capacity`), so
40
- * CreateCall fails at once instead of TrackCall reporting FAILED later. Failures after the room
41
- * exists (no gateway, dial refused) are reported to TrackCall as FAILED. Returns a stop function.
33
+ * Serves `calls.create` (a request from CreateCall) by placing each call on a Roomr node with
34
+ * Roomr's CreateCall over gRPC (placeOutboundCall); nodes come from their heartbeats on
35
+ * `roomr.nodes.<node_ref>.heartbeat`. The reply comes once the node accepted CreateCall (`{type: "ack",
36
+ * ref, nodeId}`), or with `{type: "error", code, message}` (`no_capacity` when no node took it),
37
+ * so CreateCall fails at once instead of TrackCall reporting FAILED later. While a call is being
38
+ * placed its `placements.<ref>` registry entry names the node; a replica that dies mid-placement
39
+ * leaves it behind and the sweep (every replica) ends the call. Returns a stop function.
42
40
  */
43
41
  export declare function runOutboundCalls(config: {
44
42
  natsUrl?: NatsTarget;
45
43
  /** The session registry's bucket (default Sessions.SESSIONS_BUCKET; tests). */
46
44
  sessionsBucket?: string;
47
45
  nc?: NatsConnection;
46
+ /** Roomr calls (default: a channel pool over plaintext gRPC). */
47
+ roomr?: Roomr.RoomrCalls;
48
+ /** Where calls are dialed (default: fonoster.yaml's routr). */
49
+ outbound?: OutboundTarget;
50
+ /** How long a placement entry may sit unchanged before the sweep ends its call (tests). */
51
+ placementStaleMs?: number;
48
52
  }): Promise<() => Promise<void>>;
@@ -9,7 +9,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
9
9
  });
10
10
  };
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.natsRequester = natsRequester;
13
12
  exports.callTracker = callTracker;
14
13
  exports.runOutboundCalls = runOutboundCalls;
15
14
  /**
@@ -35,65 +34,71 @@ const logger_1 = require("@fonoster/logger");
35
34
  const nats_1 = require("nats");
36
35
  const envs_1 = require("../envs");
37
36
  const createNodeDirectory_1 = require("./createNodeDirectory");
37
+ const placementSweep_1 = require("./placementSweep");
38
38
  const placeOutboundCall_1 = require("./placeOutboundCall");
39
39
  const logger = (0, logger_1.getLogger)({ service: "apiserver", filePath: __filename });
40
40
  const sc = (0, nats_1.StringCodec)();
41
- /** JSON request and reply over a NATS connection. */
42
- function natsRequester(nc) {
43
- return (subject, body, timeoutMs) => __awaiter(this, void 0, void 0, function* () {
44
- const msg = yield nc.request(subject, sc.encode(JSON.stringify(body)), {
45
- timeout: timeoutMs
46
- });
47
- return JSON.parse(sc.decode(msg.data));
48
- });
49
- }
50
41
  /**
51
42
  * The control plane's part of a call's status events for TrackCall: TRYING when placement starts,
52
- * `{ref, nodeId}` once a node holds the call's room (TrackCall then follows that node's
53
- * heartbeats), and FAILED when placement fails. Everything after the room exists (PROGRESS, ANSWER, BUSY, the final
54
- * room.ended) comes from the media node on the same per-call subject, so the statuses keep
55
- * flowing to every replica's TrackCall even if this replica dies.
43
+ * `{ref, node_ref}` once a node took CreateCall (TrackCall then follows that node's heartbeats), and FAILED when placement fails. Everything after that (call.ringing,
44
+ * call.answered, call.ended) comes from the Roomr node on `roomr.events.<ref>`, so the statuses
45
+ * keep flowing to every replica's TrackCall even if this replica dies.
56
46
  */
57
47
  function callTracker(nc, ref) {
58
48
  const publish = (body) => nc.publish((0, envs_1.callEventsSubject)(ref), sc.encode(JSON.stringify(body)));
59
49
  publish({ ref, status: "TRYING" });
60
50
  return {
61
51
  placed(nodeId) {
62
- publish({ ref, nodeId });
52
+ publish({ ref, node_ref: nodeId });
63
53
  },
64
54
  failed() {
65
55
  publish({ ref, status: "FAILED" });
66
56
  }
67
57
  };
68
58
  }
59
+ /** Routr and the roomr peer from the config (fonoster.yaml `routr`). */
60
+ function configuredTarget() {
61
+ const { username, password } = envs_1.ROUTR_ROOMR_PEER;
62
+ return Object.assign({ proxy: envs_1.ROUTR_SIP_PROXY }, (password ? { auth: { username, password } } : {}));
63
+ }
69
64
  /**
70
- * Serves `calls.create` (a request from CreateCall) by placing each call on the media nodes.
71
- * Takes over from the Asterisk originate the apiserver used before the rebuild (cleanbreak
72
- * CB-B2). The reply comes as soon as a node has accepted the call's room (`{type: "ack", ref,
73
- * nodeId}`), or with `{type: "error", code, message}` when no node took it (`no_capacity`), so
74
- * CreateCall fails at once instead of TrackCall reporting FAILED later. Failures after the room
75
- * exists (no gateway, dial refused) are reported to TrackCall as FAILED. Returns a stop function.
65
+ * Serves `calls.create` (a request from CreateCall) by placing each call on a Roomr node with
66
+ * Roomr's CreateCall over gRPC (placeOutboundCall); nodes come from their heartbeats on
67
+ * `roomr.nodes.<node_ref>.heartbeat`. The reply comes once the node accepted CreateCall (`{type: "ack",
68
+ * ref, nodeId}`), or with `{type: "error", code, message}` (`no_capacity` when no node took it),
69
+ * so CreateCall fails at once instead of TrackCall reporting FAILED later. While a call is being
70
+ * placed its `placements.<ref>` registry entry names the node; a replica that dies mid-placement
71
+ * leaves it behind and the sweep (every replica) ends the call. Returns a stop function.
76
72
  */
77
73
  function runOutboundCalls(config) {
78
74
  return __awaiter(this, void 0, void 0, function* () {
79
- var _a, _b;
75
+ var _a, _b, _c, _d;
80
76
  const nc = (_a = config.nc) !== null && _a !== void 0 ? _a : (yield (0, nats_1.connect)(Object.assign(Object.assign({}, (0, common_1.natsConnectOptions)((_b = config.natsUrl) !== null && _b !== void 0 ? _b : "")), { maxReconnectAttempts: -1 })));
81
77
  const nodes = (0, createNodeDirectory_1.createNodeDirectory)();
82
- const request = natsRequester(nc);
83
- // The session registry (add-media-node 3.2): every live node at once, then changes.
78
+ const pool = config.roomr ? undefined : common_1.Roomr.createRoomrPool();
79
+ const roomr = (_c = config.roomr) !== null && _c !== void 0 ? _c : pool;
80
+ const outbound = (_d = config.outbound) !== null && _d !== void 0 ? _d : configuredTarget();
81
+ // The session registry holds the placements (the nodes come from their heartbeats).
84
82
  let stopWatch;
83
+ let kv;
84
+ let sweep;
85
85
  try {
86
- const kv = yield Promise.race([
86
+ kv = yield Promise.race([
87
87
  common_1.Sessions.openSessions(nc, { bucket: config.sessionsBucket }),
88
88
  new Promise((_, reject) => setTimeout(() => reject(new Error("timed out")), 5000).unref())
89
89
  ]);
90
- stopWatch = yield common_1.Sessions.watchSessions(kv, "nodes", (e) => nodes.note(e.value
91
- ? Object.assign(Object.assign({ nodeId: e.id }, e.value), { type: "node.heartbeat" }) : { type: "node.down", nodeId: e.id }, e.writtenAt.getTime()));
90
+ sweep = yield (0, placementSweep_1.createPlacementSweep)({
91
+ kv,
92
+ roomr,
93
+ nodeUp: (nodeRef) => nodes.live(nodeRef),
94
+ failed: (ref) => nc.publish((0, envs_1.callEventsSubject)(ref), sc.encode(JSON.stringify({ ref, status: "FAILED" }))),
95
+ staleMs: config.placementStaleMs
96
+ });
92
97
  }
93
98
  catch (e) {
94
99
  logger.warn(`session registry unavailable (is JetStream on?); placing from heartbeats only: ${e.message}`);
95
100
  }
96
- const status = nc.subscribe("media.*.heartbeat", {
101
+ const status = nc.subscribe(envs_1.NODE_HEARTBEAT_WILDCARD, {
97
102
  callback: (err, msg) => {
98
103
  if (err)
99
104
  return;
@@ -130,12 +135,17 @@ function runOutboundCalls(config) {
130
135
  msg.respond(sc.encode(JSON.stringify(body)));
131
136
  };
132
137
  const tracker = callTracker(nc, call.ref);
133
- (0, placeOutboundCall_1.placeOutboundCall)(request, nodes, call, {
134
- onRoom: (nodeId) => {
135
- tracker.placed(nodeId);
136
- reply({ type: "ack", ref: call.ref, nodeId });
137
- }
138
- }).then((placed) => logger.verbose("outbound call placed", Object.assign({ ref: call.ref }, placed)), (e) => {
138
+ (0, placeOutboundCall_1.placeOutboundCall)({ roomr, nodes, outbound }, call, {
139
+ // The registry entry goes first (control-plane "Outbound calls are registered before
140
+ // they are placed"), rewritten when the call moves to another node.
141
+ onAttempt: (nodeId, controlAddr) => sweep === null || sweep === void 0 ? void 0 : sweep.placing(call.ref, nodeId, controlAddr)
142
+ }).then((placed) => {
143
+ tracker.placed(placed.nodeId);
144
+ void (sweep === null || sweep === void 0 ? void 0 : sweep.placed(call.ref));
145
+ reply({ type: "ack", ref: call.ref, nodeId: placed.nodeId });
146
+ logger.verbose("outbound call placed", Object.assign({ ref: call.ref }, placed));
147
+ }, (e) => {
148
+ void (sweep === null || sweep === void 0 ? void 0 : sweep.placed(call.ref));
139
149
  tracker.failed();
140
150
  reply({
141
151
  type: "error",
@@ -150,6 +160,8 @@ function runOutboundCalls(config) {
150
160
  yield nc.flush();
151
161
  return () => __awaiter(this, void 0, void 0, function* () {
152
162
  stopWatch === null || stopWatch === void 0 ? void 0 : stopWatch();
163
+ sweep === null || sweep === void 0 ? void 0 : sweep.stop();
164
+ pool === null || pool === void 0 ? void 0 : pool.close();
153
165
  status.unsubscribe();
154
166
  calls.unsubscribe();
155
167
  if (!config.nc)