@cotal-ai/core 0.170.0 → 0.171.0
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.
- package/dist/agent-endpoint.d.ts +146 -5
- package/dist/agent-endpoint.d.ts.map +1 -1
- package/dist/agent-endpoint.js +69 -12
- package/dist/agent-endpoint.js.map +1 -1
- package/dist/connector-setup.d.ts +2 -0
- package/dist/connector-setup.d.ts.map +1 -1
- package/dist/endpoint-action.d.ts +2 -2
- package/dist/endpoint-action.js +6 -7
- package/dist/endpoint-action.js.map +1 -1
- package/dist/endpoint-boot-memberships.d.ts +71 -0
- package/dist/endpoint-boot-memberships.d.ts.map +1 -0
- package/dist/endpoint-boot-memberships.js +119 -0
- package/dist/endpoint-boot-memberships.js.map +1 -0
- package/dist/endpoint-journal.d.ts.map +1 -1
- package/dist/endpoint-journal.js +14 -6
- package/dist/endpoint-journal.js.map +1 -1
- package/dist/endpoint-provisioning.d.ts +73 -0
- package/dist/endpoint-provisioning.d.ts.map +1 -0
- package/dist/endpoint-provisioning.js +122 -0
- package/dist/endpoint-provisioning.js.map +1 -0
- package/dist/endpoint.d.ts +10 -33
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/endpoint.js +44 -150
- package/dist/endpoint.js.map +1 -1
- package/dist/provision-permission-builders.d.ts +356 -0
- package/dist/provision-permission-builders.d.ts.map +1 -0
- package/dist/provision-permission-builders.js +1383 -0
- package/dist/provision-permission-builders.js.map +1 -0
- package/dist/provision-permissions.d.ts +2 -47
- package/dist/provision-permissions.d.ts.map +1 -1
- package/dist/provision-permissions.js +9 -1378
- package/dist/provision-permissions.js.map +1 -1
- package/package.json +1 -1
package/dist/endpoint.js
CHANGED
|
@@ -32,7 +32,7 @@ import { isConsumerNotFound, isJetStreamMissing, isStreamNotFound } from "./jets
|
|
|
32
32
|
import { assertValidKind } from "./agent-file.js";
|
|
33
33
|
import { assertValidName } from "./resolve.js";
|
|
34
34
|
import { nextHeartbeat } from "./presence-heartbeat.js";
|
|
35
|
-
import { anycastStoreDefinition,
|
|
35
|
+
import { anycastStoreDefinition, taskDurableConfig, PRESENCE_STORAGE } from "./streams.js";
|
|
36
36
|
import { DELIVERY_LIMIT_HEADER, PLANE3_MAX_MSGS_PER_SUBJECT } from "./backup-config.js";
|
|
37
37
|
import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
|
|
38
38
|
import {} from "@nats-io/jetstream";
|
|
@@ -47,11 +47,13 @@ import { EndpointDurableBackstop } from "./endpoint-durable-backstop.js";
|
|
|
47
47
|
import { EndpointSubscriptions, membershipConsumerReleased } from "./endpoint-subscriptions.js";
|
|
48
48
|
import { EndpointChannelDiscovery } from "./endpoint-channel-discovery.js";
|
|
49
49
|
import { EndpointLiveness } from "./endpoint-liveness.js";
|
|
50
|
+
import { EndpointProvisioning } from "./endpoint-provisioning.js";
|
|
51
|
+
import { EndpointBootMemberships } from "./endpoint-boot-memberships.js";
|
|
50
52
|
import { ackWaitOf, authenticatedChannelMessage, durableDelivery, isRecord } from "./endpoint-inbound.js";
|
|
51
53
|
import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
|
|
52
54
|
import { isCasLoss } from "./endpoint-records.js";
|
|
53
55
|
import { ANYCAST_CANCEL_OP, ANYCAST_NOTICE_KEY, ANYCAST_RECORDS_CREDENTIAL_OUTDATED, ANYCAST_STATUS_OP, ANYCAST_TAKES_OP, AnycastRequestAuthority, isAnycastSeq, } from "./anycast-requests.js";
|
|
54
|
-
import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable,
|
|
56
|
+
import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
|
|
55
57
|
import { isPermissionDenied } from "./permission-denied.js";
|
|
56
58
|
export { isPermissionDenied };
|
|
57
59
|
export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
|
|
@@ -3079,26 +3081,26 @@ export class CotalEndpoint extends EventEmitter {
|
|
|
3079
3081
|
throw error;
|
|
3080
3082
|
}
|
|
3081
3083
|
}
|
|
3082
|
-
/**
|
|
3083
|
-
*
|
|
3084
|
+
/** Stream creation and the privileged DM, DELIVER and TASK durable provisioning of this endpoint.
|
|
3085
|
+
* Every dependency is read when it is used, so a field assigned after construction is seen. */
|
|
3086
|
+
provisioning = new EndpointProvisioning({
|
|
3087
|
+
jsm: () => this.jsm,
|
|
3088
|
+
space: () => this.space,
|
|
3089
|
+
authed: () => this.authed,
|
|
3090
|
+
notLiveMsg: () => this.notLiveMsg(),
|
|
3091
|
+
manager: () => this.manager(),
|
|
3092
|
+
});
|
|
3093
|
+
/** Forwards to the provisioning component's {@link EndpointProvisioning.ensureStreams}. */
|
|
3084
3094
|
async ensureStreams() {
|
|
3085
|
-
|
|
3086
|
-
throw new Error(this.notLiveMsg());
|
|
3087
|
-
await createSpaceStreams(this.jsm, this.space);
|
|
3095
|
+
return this.provisioning.ensureStreams();
|
|
3088
3096
|
}
|
|
3089
3097
|
/** Create this open space's message streams if they are not there yet, as a consuming endpoint
|
|
3090
3098
|
* does when it starts. For a sender that consumes nothing and may be the space's first
|
|
3091
3099
|
* participant (#7045). An authenticated broker's streams come from its setup, and its agents may
|
|
3092
3100
|
* not create them, so this throws there. */
|
|
3093
3101
|
async ensureOpenSpaceStreams() {
|
|
3094
|
-
|
|
3095
|
-
|
|
3096
|
-
await createSpaceStreams(await this.manager(), this.space);
|
|
3097
|
-
}
|
|
3098
|
-
// (v3) The old `provisionMembership` — manager/provisioner-written boot membership at spawn — is GONE.
|
|
3099
|
-
// Boot durable membership is now the AGENT self-joining its durable boot channels via the daemon's
|
|
3100
|
-
// `ctl.delivery` op at connect ({@link armBootDurableMemberships}), reconciled on outage. The
|
|
3101
|
-
// primitive it wrapped, {@link durableJoinFor}, is now driven by the daemon's `ctl.delivery` handler.
|
|
3102
|
+
return this.provisioning.ensureOpenSpaceStreams();
|
|
3103
|
+
}
|
|
3102
3104
|
/**
|
|
3103
3105
|
* Privileged: pre-create an agent's DM inbox durable (auth mode), so the agent can BIND
|
|
3104
3106
|
* it without holding CONSUMER.CREATE on DM_<space>. The creator sets the filter to
|
|
@@ -3107,56 +3109,11 @@ export class CotalEndpoint extends EventEmitter {
|
|
|
3107
3109
|
* safe to call again on manager restart. The caller must be permissive on DM_<space>.
|
|
3108
3110
|
*/
|
|
3109
3111
|
async provisionDmInbox(owner, actor, lifecycleUid) {
|
|
3110
|
-
|
|
3111
|
-
}
|
|
3112
|
-
/**
|
|
3113
|
-
* (SPEC §8). Info-first: an existing durable (a manager-restart re-provision of the SAME uid, or
|
|
3114
|
-
* the same lifecycle's own restart) is kept as-is, preserving the ORIGINAL frontier — the
|
|
3115
|
-
* activation moment never moves. A fresh lifecycle captures the DM stream's current `last_seq` and
|
|
3116
|
-
* starts delivery at frontier+1, so a same-alias successor inherits none of the predecessor's
|
|
3117
|
-
* pending DMs (its filter is the shared alias subject `inst.>`; the FRONTIER, not the subject, is
|
|
3118
|
-
* the cut).
|
|
3119
|
-
*
|
|
3120
|
-
* HONESTY (panel-locked): the no-gap guarantee (a DM published between the capture and the create
|
|
3121
|
-
* lands ABOVE the frontier and is delivered) holds ONLY under ONE provisioner per lifecycle uid —
|
|
3122
|
-
* the manager provisions sequentially, which satisfies it. Under CONCURRENT same-uid provisioners
|
|
3123
|
-
* (a split-brain manager), a higher-frontier winner excludes the loser's N+1..M capture window:
|
|
3124
|
-
* the lost-race branch below keeps the winner's durable unconditionally. No per-uid serialization
|
|
3125
|
-
* or persisted-frontier machinery is added in this slice; concurrent same-uid provisioning is
|
|
3126
|
-
* out-of-contract (at-least-once best-effort). */
|
|
3112
|
+
return this.provisioning.provisionDmInbox(owner, actor, lifecycleUid);
|
|
3113
|
+
}
|
|
3114
|
+
/** Forwards to the provisioning component's {@link EndpointProvisioning.ensureDmDurable}. */
|
|
3127
3115
|
async ensureDmDurable(owner, actor, lifecycleUid, opts) {
|
|
3128
|
-
|
|
3129
|
-
const stream = dmStream(this.space);
|
|
3130
|
-
const name = dmDurable(owner, actor, lifecycleUid);
|
|
3131
|
-
try {
|
|
3132
|
-
await jsm.consumers.info(stream, name);
|
|
3133
|
-
return; // this lifecycle's durable exists — keep its original frontier
|
|
3134
|
-
}
|
|
3135
|
-
catch (e) {
|
|
3136
|
-
if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
|
|
3137
|
-
throw e;
|
|
3138
|
-
// Genuinely absent consumer: create it below. A denial is not absence.
|
|
3139
|
-
}
|
|
3140
|
-
const frontier = (await jsm.streams.info(stream)).state.last_seq;
|
|
3141
|
-
try {
|
|
3142
|
-
await jsm.consumers.add(stream, dmDurableConfig(this.space, owner, actor, lifecycleUid, { ...opts, activationFrontier: frontier }));
|
|
3143
|
-
}
|
|
3144
|
-
catch (e) {
|
|
3145
|
-
// A concurrent same-lifecycle provisioner may have won the create with an earlier frontier —
|
|
3146
|
-
// if the durable now exists it is authoritative; anything else stays a loud failure.
|
|
3147
|
-
try {
|
|
3148
|
-
await jsm.consumers.info(stream, name);
|
|
3149
|
-
return;
|
|
3150
|
-
}
|
|
3151
|
-
catch (probeError) {
|
|
3152
|
-
// The probe never creates a successful result: it either proves the concurrent winner above,
|
|
3153
|
-
// or the original create failure stays authoritative. Preserve a denial from the probe because
|
|
3154
|
-
// it names the missing capability more accurately than an unrelated create conflict.
|
|
3155
|
-
if (isPermissionDenied(probeError))
|
|
3156
|
-
throw probeError;
|
|
3157
|
-
}
|
|
3158
|
-
throw e;
|
|
3159
|
-
}
|
|
3116
|
+
return this.provisioning.ensureDmDurable(owner, actor, lifecycleUid, opts);
|
|
3160
3117
|
}
|
|
3161
3118
|
/**
|
|
3162
3119
|
* Privileged: pre-create an agent's bind-only Plane-3 DELIVER durable (`dlv_<id>`, filtered to
|
|
@@ -3166,8 +3123,7 @@ export class CotalEndpoint extends EventEmitter {
|
|
|
3166
3123
|
* acks them via native JetStream (SPEC §8). Idempotent. The caller must be permissive on DLV.
|
|
3167
3124
|
*/
|
|
3168
3125
|
async provisionDlvInbox(owner, actor, lifecycleUid) {
|
|
3169
|
-
|
|
3170
|
-
await jsm.consumers.add(dlvStream(this.space), dlvDurableConfig(this.space, owner, actor, lifecycleUid));
|
|
3126
|
+
return this.provisioning.provisionDlvInbox(owner, actor, lifecycleUid);
|
|
3171
3127
|
}
|
|
3172
3128
|
/**
|
|
3173
3129
|
* Privileged: pre-create a role's shared TASK work-queue durable (auth mode), so agents
|
|
@@ -3176,8 +3132,7 @@ export class CotalEndpoint extends EventEmitter {
|
|
|
3176
3132
|
* Idempotent per role. The caller must be permissive on TASK_<space>.
|
|
3177
3133
|
*/
|
|
3178
3134
|
async provisionTaskQueue(role) {
|
|
3179
|
-
|
|
3180
|
-
await jsm.consumers.add(taskStream(this.space), taskDurableConfig(this.space, role));
|
|
3135
|
+
return this.provisioning.provisionTaskQueue(role);
|
|
3181
3136
|
}
|
|
3182
3137
|
// ---- Plane-3: durable backstop (SPEC §8) — privileged, hosted by the server-side DELIVERY DAEMON ----
|
|
3183
3138
|
//
|
|
@@ -4390,99 +4345,38 @@ export class CotalEndpoint extends EventEmitter {
|
|
|
4390
4345
|
}
|
|
4391
4346
|
return reply.data;
|
|
4392
4347
|
}
|
|
4348
|
+
/** The boot durable self-join and its reconcile, and the membership read the leave path uses, of
|
|
4349
|
+
* this endpoint. Every dependency is read when it is used, and every endpoint method is looked up
|
|
4350
|
+
* at call time, so a test that replaces one on the endpoint is seen here. */
|
|
4351
|
+
bootMemberships = new EndpointBootMemberships({
|
|
4352
|
+
channels: () => this.channels,
|
|
4353
|
+
plane3Channels: () => this.plane3Channels,
|
|
4354
|
+
pendingBootJoins: () => this.pendingBootJoins,
|
|
4355
|
+
stopped: () => this.stopped,
|
|
4356
|
+
requestDelivery: (op, args, timeoutMs) => this.requestDelivery(op, args, timeoutMs),
|
|
4357
|
+
requireLifecycleUid: (what) => this.requireLifecycleUid(what),
|
|
4358
|
+
deliveryClassFresh: (channel) => this.deliveryClassFresh(channel),
|
|
4359
|
+
durableJoinChannel: (channel) => this.durableJoinChannel(channel),
|
|
4360
|
+
membershipPause: (attempt) => this.membershipPause(attempt),
|
|
4361
|
+
isNoResponders: (e) => this.isNoResponders(e),
|
|
4362
|
+
emitRecoverable: (err) => this.emitRecoverable(err),
|
|
4363
|
+
});
|
|
4393
4364
|
/** Agent-side: current lifecycle memberships, or all principal-owned rows for an explicit channel,
|
|
4394
4365
|
* from the delivery service. The agent holds no read on the privileged members KV. `undefined` ⇒ NO control responder
|
|
4395
4366
|
* (open / no delivery daemon, so there is no Plane-3 and no memberships). THROWS on a responder-present RPC
|
|
4396
4367
|
* failure, so a caller can FAIL-CLOSED rather than mistaking a transient error for "no membership". */
|
|
4397
4368
|
async fetchMemberships(channel) {
|
|
4398
|
-
|
|
4399
|
-
try {
|
|
4400
|
-
reply = await this.requestDelivery("listMemberships", { lifecycleUid: this.requireLifecycleUid("listing durable memberships"), ...(channel === undefined ? {} : { channel }) }, 5_000);
|
|
4401
|
-
}
|
|
4402
|
-
catch (e) {
|
|
4403
|
-
if (this.isNoResponders(e))
|
|
4404
|
-
return undefined; // no delivery daemon — open / daemon-less, no Plane-3
|
|
4405
|
-
throw e; // responder present but errored — surface it (leaveChannel fails closed)
|
|
4406
|
-
}
|
|
4407
|
-
if (!reply.ok)
|
|
4408
|
-
throw new Error(reply.error ?? "listMemberships failed");
|
|
4409
|
-
return reply.data?.memberships ?? [];
|
|
4410
|
-
}
|
|
4411
|
-
/** Agent-side, first connect (auth): SELF-JOIN this session's durable boot channels via the
|
|
4412
|
-
* server-side delivery daemon — replacing the old manager-written boot membership. Each concrete
|
|
4413
|
-
* `durable`-class boot channel, and each family such as `review.>`, gets a `durableJoin` whose
|
|
4414
|
-
* returned generation seeds the leave mirror
|
|
4415
|
-
* + durable-state surface; an already-active membership (a relaunch) is idempotent (no re-catch-up).
|
|
4416
|
-
* If the daemon is down/absent at first connect (or reports a transient `durable:false`), the channel
|
|
4417
|
-
* is handed to {@link reconcileBootJoin} for capped-backoff retry — so the backstop is RESTORED once
|
|
4418
|
-
* the daemon recovers, not left silently live-only. Until a membership exists the channel renders
|
|
4419
|
-
* degraded in `cotal_channels` ({@link hasDurableMembership}). */
|
|
4420
|
-
async armBootDurableMemberships() {
|
|
4421
|
-
for (const channel of this.channels) {
|
|
4422
|
-
if (this.plane3Channels.has(channel))
|
|
4423
|
-
continue;
|
|
4424
|
-
// A family (`review.>`) asks for its row whatever the default class: each channel under it decides
|
|
4425
|
-
// its own at fan-out (#5404). Any other pattern has no durable membership.
|
|
4426
|
-
if (!isChannelFamily(channel)) {
|
|
4427
|
-
if (!isConcreteChannel(channel))
|
|
4428
|
-
continue;
|
|
4429
|
-
// A missing channel row legitimately resolves through the defaults. A failed/denied registry
|
|
4430
|
-
// read does not prove the channel is live-only, so let it fail startup loudly.
|
|
4431
|
-
const cls = await this.deliveryClassFresh(channel);
|
|
4432
|
-
if (cls !== "durable")
|
|
4433
|
-
continue;
|
|
4434
|
-
}
|
|
4435
|
-
try {
|
|
4436
|
-
const r = await this.durableJoinChannel(channel);
|
|
4437
|
-
if (r.durable)
|
|
4438
|
-
this.plane3Channels.set(channel, r.generation ?? 0);
|
|
4439
|
-
else
|
|
4440
|
-
void this.reconcileBootJoin(channel); // present but not yet durable — reconcile to recovery
|
|
4441
|
-
}
|
|
4442
|
-
catch (e) {
|
|
4443
|
-
if (!this.isNoResponders(e))
|
|
4444
|
-
this.emitRecoverable(e); // no daemon ⇒ retry until it recovers
|
|
4445
|
-
void this.reconcileBootJoin(channel);
|
|
4446
|
-
}
|
|
4447
|
-
}
|
|
4369
|
+
return this.bootMemberships.fetchMemberships(channel);
|
|
4448
4370
|
}
|
|
4449
|
-
/**
|
|
4450
|
-
|
|
4451
|
-
|
|
4452
|
-
* forever after the daemon recovers (and the lease-based health could then read "active" with no owner
|
|
4453
|
-
* membership). This loop is the reconcile that closes that gap. Idempotent — a channel already pending
|
|
4454
|
-
* is not double-driven; survives reconnect (it re-issues `durableJoinChannel` on the current connection). */
|
|
4455
|
-
async reconcileBootJoin(channel) {
|
|
4456
|
-
if (this.pendingBootJoins.has(channel))
|
|
4457
|
-
return; // already reconciling
|
|
4458
|
-
this.pendingBootJoins.add(channel);
|
|
4459
|
-
for (let attempt = 0;; attempt++) {
|
|
4460
|
-
await this.membershipPause(attempt);
|
|
4461
|
-
if (this.stopped || !this.channels.includes(channel) || this.plane3Channels.has(channel)) {
|
|
4462
|
-
this.pendingBootJoins.delete(channel);
|
|
4463
|
-
return; // stopped, left, or another path established it
|
|
4464
|
-
}
|
|
4465
|
-
try {
|
|
4466
|
-
const r = await this.durableJoinChannel(channel);
|
|
4467
|
-
if (r.durable) {
|
|
4468
|
-
this.plane3Channels.set(channel, r.generation ?? 0);
|
|
4469
|
-
this.pendingBootJoins.delete(channel);
|
|
4470
|
-
return;
|
|
4471
|
-
}
|
|
4472
|
-
// present but durable:false (e.g. catch-up window evicted) — keep retrying; the channel stays
|
|
4473
|
-
// honestly degraded meanwhile, never silently "active".
|
|
4474
|
-
}
|
|
4475
|
-
catch (e) {
|
|
4476
|
-
if (attempt === 0 && !this.isNoResponders(e))
|
|
4477
|
-
this.emitRecoverable(new Error(`channel "${channel}": boot durable self-join not yet established - retrying until the delivery daemon is reachable (${e.message})`));
|
|
4478
|
-
}
|
|
4479
|
-
}
|
|
4371
|
+
/** Forwards to the boot-membership component's {@link EndpointBootMemberships.armBootDurableMemberships}. */
|
|
4372
|
+
async armBootDurableMemberships() {
|
|
4373
|
+
return this.bootMemberships.armBootDurableMemberships();
|
|
4480
4374
|
}
|
|
4481
4375
|
/** True if this session holds an established Plane-3 durable membership for `channel` (in `plane3Channels`).
|
|
4482
4376
|
* Drives the membership-aware delivery-health surface: a joined durable channel that is NOT yet a member
|
|
4483
4377
|
* (boot self-join pending / daemon down) must render degraded, never "active" off a live lease alone. */
|
|
4484
4378
|
hasDurableMembership(channel) {
|
|
4485
|
-
return this.
|
|
4379
|
+
return this.bootMemberships.hasDurableMembership(channel);
|
|
4486
4380
|
}
|
|
4487
4381
|
/** Lazily obtain a JetStream manager — so a non-consuming endpoint (e.g. the supervisor,
|
|
4488
4382
|
* consume:false) can still pre-create others' durables. */
|