@941design/marmot 0.2.0-alpha.0 → 0.2.0-alpha.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.
- package/CHANGELOG.md +30 -0
- package/dist/account/teardown.d.ts +66 -3
- package/dist/account/teardown.js +24 -2
- package/dist/client/admission-cleanup.d.ts +197 -0
- package/dist/client/admission-cleanup.js +635 -0
- package/dist/client/adoption-proof.d.ts +39 -0
- package/dist/client/adoption-proof.js +102 -0
- package/dist/client/before-publish-hooks.js +3 -1
- package/dist/client/commit-redrive.d.ts +28 -4
- package/dist/client/commit-redrive.js +54 -1
- package/dist/client/confirm-hooks.d.ts +6 -1
- package/dist/client/confirm-hooks.js +15 -0
- package/dist/client/create-client.d.ts +107 -3
- package/dist/client/create-client.js +114 -7
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -0
- package/dist/client/group-history.d.ts +26 -0
- package/dist/client/group-history.js +77 -7
- package/dist/client/group-records.d.ts +39 -2
- package/dist/client/group-records.js +88 -5
- package/dist/client/group-runtime.d.ts +30 -3
- package/dist/client/group-runtime.js +131 -21
- package/dist/client/group-snapshot.d.ts +7 -1
- package/dist/client/group-snapshot.js +23 -2
- package/dist/client/index.d.ts +4 -1
- package/dist/client/ingest.js +47 -13
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -0
- package/dist/client/opaque-candidates.d.ts +2 -1
- package/dist/client/opaque-candidates.js +2 -1
- package/dist/client/own-change-outbox.js +2 -0
- package/dist/client/pipeline.d.ts +30 -1
- package/dist/client/pipeline.js +142 -21
- package/dist/client/reentrancy-guard.d.ts +6 -0
- package/dist/client/reentrancy-guard.js +6 -0
- package/dist/history/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/fencing.d.ts +41 -0
- package/dist/history/fencing.js +67 -7
- package/dist/history/index.d.ts +2 -1
- package/dist/history/index.js +2 -1
- package/dist/history/own-change.d.ts +13 -1
- package/dist/invitations/decline.d.ts +8 -2
- package/dist/invitations/decline.js +9 -3
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/index.d.ts +4 -2
- package/dist/invitations/index.js +4 -2
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +61 -6
- package/dist/invitations/invite.js +187 -51
- package/dist/invitations/welcome-processor.d.ts +20 -1
- package/dist/invitations/welcome-processor.js +81 -20
- package/dist/shared/errors.d.ts +7 -0
- package/dist/shared/errors.js +11 -0
- package/dist/shared/index.d.ts +1 -1
- package/dist/shared/index.js +1 -1
- package/dist/storage/index.d.ts +10 -0
- package/dist/storage/index.js +33 -1
- package/dist/storage/lease.d.ts +13 -0
- package/dist/storage/lease.js +51 -0
- package/package.json +2 -2
|
@@ -5,10 +5,10 @@ import { HISTORY_BACKEND_TIMEOUT_MS } from './group-history.js';
|
|
|
5
5
|
import { DEFAULT_REMOVAL_SETTLE_MS } from './group-removal.js';
|
|
6
6
|
import { createDeviceService, createTeardownService, DEFAULT_LEAVE_TIMEOUT_MS, DEFAULT_MAX_GIFT_WRAP_BYTES, DEFAULT_PROMPT_RATE_LIMIT, enforceStateProofs, supersedeOwnForget, } from '../account/index.js';
|
|
7
7
|
import { createInboxHandlerRegistry, createInboxSubscription, createRumorDemux, DEFAULT_SEEN_SET_CAP, } from '../inbox/index.js';
|
|
8
|
-
import { createInvitationsService, createWelcomeService, DEFAULT_INVITE_RETENTION_MS, DEFAULT_PROPOSAL_DEFERRAL_TIMEOUT_MS, handleKeyPackageOffer, listKeyPackageOffers, resolveInboxRelays, sendKeyPackageOffer, validateOfferOptions, } from '../invitations/index.js';
|
|
8
|
+
import { createInvitationsService, createWelcomeService, declineCandidatePage, declineScanOptions, DEFAULT_INVITE_RETENTION_MS, DEFAULT_PROPOSAL_DEFERRAL_TIMEOUT_MS, handleKeyPackageOffer, listKeyPackageOffers, resolveInboxRelays, sendKeyPackageOffer, validateOfferOptions, } from '../invitations/index.js';
|
|
9
9
|
import { createKeyPackage, countKeyPackages, fetchKeyPackageEvents, resolveWriteRelays, forgetKeyPackage, keyPackageStatus, recordKeyPackageGroupRef, listKeyPackages, observeKeyPackages, purgeAllExpiredSuperseded, resumePendingIntents, probeParkedUnconfirmed, createParkedProbeState, rotateKeyPackage, retireKeyPackagesSignedWith, DEFAULT_CIPHERSUITE_NAME, } from '../key-packages/index.js';
|
|
10
10
|
import { defaultCryptoProvider, getCiphersuiteImpl } from '@941design/marmot-engine/mls';
|
|
11
|
-
import { MarmotError, RUMOR_KINDS } from '../shared/index.js';
|
|
11
|
+
import { isMarmotError, MarmotError, RUMOR_KINDS } from '../shared/index.js';
|
|
12
12
|
import { createBeforeCreateGroupGates } from './before-create-group.js';
|
|
13
13
|
import { createBeforePublishRegistry } from './before-publish-hooks.js';
|
|
14
14
|
import { createGroupRegistry } from './group-runtime.js';
|
|
@@ -18,7 +18,9 @@ import { fetchHistoryPages } from './history-pages.js';
|
|
|
18
18
|
import { createLifecycleEvents } from './lifecycle-events.js';
|
|
19
19
|
import { sameAccountClientConfig } from './client-config.js';
|
|
20
20
|
import { permissions } from './permissions.js';
|
|
21
|
-
import { ACCOUNT_SCOPE, createReentrancyGuard, DEVICE_SCOPE } from './reentrancy-guard.js';
|
|
21
|
+
import { ACCOUNT_SCOPE, createReentrancyGuard, DEVICE_SCOPE, GROUP_CONSUMER_SURFACES } from './reentrancy-guard.js';
|
|
22
|
+
import { readInvitationOutcome, RECOVERY_READ_INBOX_SURFACES } from './invitation-outcomes.js';
|
|
23
|
+
import { readCleanupDisposition } from './admission-cleanup.js';
|
|
22
24
|
// `satisfies Record<...>` (rather than a `Set` literal typed only as
|
|
23
25
|
// `Set<MarmotClientEventName>`) makes a member added to or removed from
|
|
24
26
|
// `MarmotClientEvents` without a matching update here a compile error,
|
|
@@ -46,6 +48,8 @@ const EVENT_NAME_KEYS = {
|
|
|
46
48
|
welcomeRestored: true,
|
|
47
49
|
welcomeReconcileFailed: true,
|
|
48
50
|
welcomeDeclined: true,
|
|
51
|
+
declineCandidate: true,
|
|
52
|
+
cleanupDisposition: true,
|
|
49
53
|
inboxDisposition: true,
|
|
50
54
|
handlerSlow: true,
|
|
51
55
|
groupJoined: true,
|
|
@@ -93,8 +97,6 @@ const MIN_RATCHET_SKIP_MARGIN = 32;
|
|
|
93
97
|
const MAX_RATCHET_SKIP_MARGIN = 100;
|
|
94
98
|
// The ceiling `requestWithDeadline` itself enforces (32-bit setTimeout delay); also `leaveTimeoutMs`'s (a timer).
|
|
95
99
|
const MAX_HISTORY_TIMEOUT_MS = 2_147_483_647;
|
|
96
|
-
/** S3 (AC-RE-2): the consumer-supplied surfaces whose live frame (on ANY group) blocks a devices.* op from enqueueing. */
|
|
97
|
-
const GROUP_CONSUMER_SURFACES = ['onConfirm', 'onBeforePublish', 'verifier', 'onProposal'];
|
|
98
100
|
const DEFAULT_TIMERS = Object.freeze({
|
|
99
101
|
set: (callback, ms) => setTimeout(callback, ms),
|
|
100
102
|
clear: (handle) => clearTimeout(handle),
|
|
@@ -492,7 +494,10 @@ export function createMarmotClientWith(options, internal) {
|
|
|
492
494
|
guard.detached(() => {
|
|
493
495
|
for (const listener of [...(listeners.get(event) ?? [])]) {
|
|
494
496
|
try {
|
|
495
|
-
listener(payload);
|
|
497
|
+
const returned = listener(payload);
|
|
498
|
+
// An async listener's rejection is the listener's own: never an unhandled rejection of the client.
|
|
499
|
+
if (typeof returned?.then === 'function')
|
|
500
|
+
returned.then(undefined, () => undefined);
|
|
496
501
|
}
|
|
497
502
|
catch {
|
|
498
503
|
// A throwing consumer listener must not break the operation that emitted.
|
|
@@ -520,6 +525,34 @@ export function createMarmotClientWith(options, internal) {
|
|
|
520
525
|
if (disposed)
|
|
521
526
|
throw new MarmotError('disposed', `${member}: client has been disposed`);
|
|
522
527
|
}
|
|
528
|
+
/**
|
|
529
|
+
* The signer's account key (epic marmot-invitation-outcomes S4, SC-3 I9c): the account cleanup references are minted
|
|
530
|
+
* for and checked against. Asked once per client (through the guard); a failed call is asked again next time.
|
|
531
|
+
*/
|
|
532
|
+
let signerAccountKey;
|
|
533
|
+
function signerAccount() {
|
|
534
|
+
if (signerAccountKey === undefined) {
|
|
535
|
+
const pending = guard.call(ACCOUNT_SCOPE, 'signer', () => ctx.signer.getPublicKey());
|
|
536
|
+
signerAccountKey = pending;
|
|
537
|
+
pending.catch(() => {
|
|
538
|
+
if (signerAccountKey === pending)
|
|
539
|
+
signerAccountKey = undefined;
|
|
540
|
+
});
|
|
541
|
+
}
|
|
542
|
+
return signerAccountKey;
|
|
543
|
+
}
|
|
544
|
+
/** SC-9 for `invitations.declineCandidates`: `reentrant` inside an account-scope frame other than an inbox surface. */
|
|
545
|
+
function assertDeclineScanAllowed() {
|
|
546
|
+
try {
|
|
547
|
+
guard.assertNotReentrant(ACCOUNT_SCOPE, 'invitations.declineCandidates');
|
|
548
|
+
}
|
|
549
|
+
catch (error) {
|
|
550
|
+
const surface = isMarmotError(error, 'reentrant') ? error.details?.['surface'] : undefined;
|
|
551
|
+
if (typeof surface === 'string' && RECOVERY_READ_INBOX_SURFACES.includes(surface))
|
|
552
|
+
return;
|
|
553
|
+
throw error;
|
|
554
|
+
}
|
|
555
|
+
}
|
|
523
556
|
// S3: the group registry (groups.create/get/list, extensions.onConfirm).
|
|
524
557
|
// Built here — after `ctx` is live, before `client` — so it closes over
|
|
525
558
|
// this exact `ctx` (INV-NO-SINGLETONS: no module-level state).
|
|
@@ -553,11 +586,39 @@ export function createMarmotClientWith(options, internal) {
|
|
|
553
586
|
onFailed: (failure) => ctx.emit('welcomeFailed', failure),
|
|
554
587
|
onRestored: (restored) => ctx.emit('welcomeRestored', restored),
|
|
555
588
|
inviteRetentionMs: ctx.inviteRetentionMs,
|
|
556
|
-
onDeclined: (declined) => ctx.emit('welcomeDeclined', declined),
|
|
589
|
+
onDeclined: (declined, { candidateId }) => ctx.emit('welcomeDeclined', { ...declined, candidateId }),
|
|
590
|
+
onCandidate: (candidate) => ctx.emit('declineCandidate', candidate),
|
|
591
|
+
// Epic marmot-invitation-outcomes S4 (SC-3 I9c): no `account` — the cleanup references' account is the signer's,
|
|
592
|
+
// the account `cleanupDisposition` checks them against (a custom store's `account` string is never authority).
|
|
557
593
|
};
|
|
558
594
|
const invitations = createInvitationsService(invitationsDeps);
|
|
559
595
|
// S9: the teardown service is built below (it needs the registry's port); the registry reaches it lazily.
|
|
560
596
|
const groupRegistry = createGroupRegistry(ctx, guard, invitations, () => teardown);
|
|
597
|
+
// Epic marmot-invitation-outcomes S1 (SC-10 A-4/A-5, ADR-019 D11): the account store's lease end closes every group's
|
|
598
|
+
// availability subscriptions `no-lease`, synchronously and without group work. Optional port member: a store without
|
|
599
|
+
// it gets that close only lazily (a background retry meeting `no-lease`, dispose — AR-2).
|
|
600
|
+
// The member is read inside the guarded block: a getter or proxy that throws on lookup gets the same cleanup and
|
|
601
|
+
// `invalid-options` as a throwing subscribe.
|
|
602
|
+
let leaseEndedOff;
|
|
603
|
+
try {
|
|
604
|
+
const accountLeaseEnded = consumerStores.account.onLeaseEnded;
|
|
605
|
+
if (typeof accountLeaseEnded === 'function') {
|
|
606
|
+
leaseEndedOff = accountLeaseEnded.call(consumerStores.account, () => groupRegistry.endAvailabilityForLease());
|
|
607
|
+
}
|
|
608
|
+
}
|
|
609
|
+
catch (err) {
|
|
610
|
+
for (const off of storeUnsubscribers.splice(0)) {
|
|
611
|
+
try {
|
|
612
|
+
off();
|
|
613
|
+
}
|
|
614
|
+
catch {
|
|
615
|
+
// construction fails with the subscribe's own error below
|
|
616
|
+
}
|
|
617
|
+
}
|
|
618
|
+
throw invalid('stores.account.onLeaseEnded threw while the client subscribed to it', err);
|
|
619
|
+
}
|
|
620
|
+
if (typeof leaseEndedOff === 'function')
|
|
621
|
+
storeUnsubscribers.push(leaseEndedOff);
|
|
561
622
|
// S4: key-packages deps — every signer/transport/STORE member already
|
|
562
623
|
// routed through the guard on the account scope, mirroring pipeline.ts's
|
|
563
624
|
// callSignerForGroup / settlePublishedRecord's guard.callSync('transport',
|
|
@@ -697,6 +758,7 @@ export function createMarmotClientWith(options, internal) {
|
|
|
697
758
|
graceWindowMs: ctx.graceWindowMs,
|
|
698
759
|
checkJoinedState: (state) => enforceStateProofs(state),
|
|
699
760
|
adoptJoinedGroup: (groupId, state, joinedAtMs, joinEvidence, invitationId, welcomeCreatedAtMs) => groupRegistry.adoptJoinedGroup(groupId, state, joinedAtMs, joinEvidence, invitationId, welcomeCreatedAtMs),
|
|
761
|
+
adoptionProofOf: (groupId, invitationId) => groupRegistry.adoptionProofOf(groupId, invitationId),
|
|
700
762
|
competing: groupRegistry.competing,
|
|
701
763
|
hasGroup: (groupId) => groupRegistry.hasGroup(groupId),
|
|
702
764
|
rotateKeyPackage: (ref) => rotateKeyPackage(keyPackagesDeps, ref),
|
|
@@ -923,6 +985,48 @@ export function createMarmotClientWith(options, internal) {
|
|
|
923
985
|
guard.assertNotReentrant(ACCOUNT_SCOPE, 'invitations.decline');
|
|
924
986
|
return welcomeService.decline(id, options);
|
|
925
987
|
},
|
|
988
|
+
outcome(id) {
|
|
989
|
+
// SC-9: decided synchronously, before anything is queued (a refused call never waits on a queue it holds).
|
|
990
|
+
try {
|
|
991
|
+
assertLive('MarmotClient.invitations.outcome');
|
|
992
|
+
}
|
|
993
|
+
catch (error) {
|
|
994
|
+
return Promise.reject(error);
|
|
995
|
+
}
|
|
996
|
+
return readInvitationOutcome({ guard, serialize: (task) => inbox.serialize(task), account: ctx.stores.account, groupStore: (groupId) => ctx.stores.groupFactory(groupId) }, id);
|
|
997
|
+
},
|
|
998
|
+
declineCandidates(options) {
|
|
999
|
+
// SC-9: decided synchronously, before any store access. Only account-scope consumer frames are refused (the
|
|
1000
|
+
// scan's account transaction would queue behind the very store call that runs the caller); the inbox
|
|
1001
|
+
// surfaces run on that scope too but hold no store transaction, so the scan proceeds from them.
|
|
1002
|
+
let paging;
|
|
1003
|
+
try {
|
|
1004
|
+
assertLive('MarmotClient.invitations.declineCandidates');
|
|
1005
|
+
assertDeclineScanAllowed();
|
|
1006
|
+
paging = declineScanOptions(options);
|
|
1007
|
+
}
|
|
1008
|
+
catch (error) {
|
|
1009
|
+
return Promise.reject(error);
|
|
1010
|
+
}
|
|
1011
|
+
// The cleanup references' account is the signer's (SC-3 I9c), as on the live path.
|
|
1012
|
+
return signerAccount().then((account) => guard.call(ACCOUNT_SCOPE, 'store', () => ctx.stores.account.transaction((tx) => declineCandidatePage(tx, { account, ...paging }))));
|
|
1013
|
+
},
|
|
1014
|
+
cleanupDisposition(ref) {
|
|
1015
|
+
// SC-9: decided synchronously, before any store access (inside readCleanupDisposition).
|
|
1016
|
+
try {
|
|
1017
|
+
assertLive('MarmotClient.invitations.cleanupDisposition');
|
|
1018
|
+
}
|
|
1019
|
+
catch (error) {
|
|
1020
|
+
return Promise.reject(error);
|
|
1021
|
+
}
|
|
1022
|
+
return readCleanupDisposition({
|
|
1023
|
+
guard,
|
|
1024
|
+
account: ctx.stores.account,
|
|
1025
|
+
groupStore: (groupId) => ctx.stores.groupFactory(groupId),
|
|
1026
|
+
accountKey: () => signerAccount(),
|
|
1027
|
+
sessionFenced: (groupId) => groupRegistry.sessionFenced(groupId),
|
|
1028
|
+
}, ref);
|
|
1029
|
+
},
|
|
926
1030
|
offers(groupId) {
|
|
927
1031
|
assertLive('MarmotClient.invitations.offers');
|
|
928
1032
|
guard.assertNotReentrant(ACCOUNT_SCOPE, 'invitations.offers');
|
|
@@ -1061,6 +1165,9 @@ export function createMarmotClientWith(options, internal) {
|
|
|
1061
1165
|
if (disposed)
|
|
1062
1166
|
return;
|
|
1063
1167
|
disposed = true;
|
|
1168
|
+
// Every group's availability ends `disposed` (recorded, not yet delivered) before any consumer teardown code runs:
|
|
1169
|
+
// a store unsubscriber that subscribes to a group's availability gets that `ended`, never a writable snapshot.
|
|
1170
|
+
groupRegistry.beginDispose();
|
|
1064
1171
|
listeners.clear();
|
|
1065
1172
|
// Each teardown step is isolated: a consumer store's throwing
|
|
1066
1173
|
// unsubscribe must not leave the other subscriptions, the group sync
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Group availability (epic marmot-invitation-outcomes S1, SC-10 A-1..A-8): one race-free observation per group of
|
|
3
|
+
* three independent facts — the fence, the sync state and the membership — plus whether the group is writable now.
|
|
4
|
+
*
|
|
5
|
+
* Availability subscriptions are their own set on the runtime ({@link GroupRuntime.availabilityListeners}). They are
|
|
6
|
+
* never terminal watchers: a fence is an ordinary observation that leaves the subscription open, and `endRuntime`
|
|
7
|
+
* never closes them. Exactly one `ended` closes a subscription, and only for the lifecycle exits
|
|
8
|
+
* ({@link AvailabilityEndReason}): a teardown purge, a failed restore taken back, client dispose, or the account
|
|
9
|
+
* lease ending (released, closed, or lost to a successor).
|
|
10
|
+
*
|
|
11
|
+
* Every change of a fact goes through one choke point on the runtime (the accessors of `fence`, `exposedState`,
|
|
12
|
+
* `caughtUp`, `sendGateOpen` and `disbanded`, group-runtime.ts `makeRuntime`), which calls
|
|
13
|
+
* {@link publishAvailability}; an observation is delivered only when the snapshot actually changed, so listeners see
|
|
14
|
+
* changes in the order they happened, each with a strictly increasing `seq` per runtime.
|
|
15
|
+
*
|
|
16
|
+
* Fence observation is monotonic within a client session: the fence setter records every fence in the client's
|
|
17
|
+
* {@link SessionFences}, and a runtime the client builds again for the group (group-runtime.ts `readLoadedRuntime`)
|
|
18
|
+
* starts fenced from it even when the durable marker could not be written. Nothing here awaits, schedules work or
|
|
19
|
+
* touches a store: {@link closeAvailability} and {@link closeAllAvailability} are synchronous, which is what lets the
|
|
20
|
+
* lease-end close run inside the store's release barrier.
|
|
21
|
+
*/
|
|
22
|
+
import { type FenceCause } from '../history/fencing.js';
|
|
23
|
+
import type { GroupRuntime } from './group-runtime.js';
|
|
24
|
+
export type { FenceCause };
|
|
25
|
+
/** The three independent facts of a group, and whether an own write may be attempted now. */
|
|
26
|
+
export interface GroupAvailability {
|
|
27
|
+
/** `fenced` once this device's state for the group can no longer be trusted (no in-place lift). */
|
|
28
|
+
readonly fence: {
|
|
29
|
+
readonly state: 'clear';
|
|
30
|
+
} | {
|
|
31
|
+
readonly state: 'fenced';
|
|
32
|
+
readonly cause: FenceCause;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* `synced` once a complete history pass ran since the last connectivity gap (`caughtUp`) and, for a group loaded
|
|
36
|
+
* from the store, the send gate opened (it opens on the first such pass after the load, AC-PIPE-15).
|
|
37
|
+
*/
|
|
38
|
+
readonly sync: 'syncing' | 'synced';
|
|
39
|
+
/** `membership-lost`: the local leaf was removed (revisable or settled); `disbanded`: a peer disband was selected. */
|
|
40
|
+
readonly membership: 'member' | 'membership-lost' | 'disbanded';
|
|
41
|
+
/** `clear && synced && member && lease live`. A clear fence alone never promises it. */
|
|
42
|
+
readonly writable: boolean;
|
|
43
|
+
}
|
|
44
|
+
/** Why an availability subscription ended. */
|
|
45
|
+
export type AvailabilityEndReason = 'torn-down' | 'restore-undone' | 'disposed' | 'no-lease';
|
|
46
|
+
/** What an availability listener receives: changes, then at most one `ended` (whose `final.writable` is `false`). */
|
|
47
|
+
export type AvailabilityObservation = {
|
|
48
|
+
readonly type: 'availability';
|
|
49
|
+
readonly seq: number;
|
|
50
|
+
readonly availability: GroupAvailability;
|
|
51
|
+
} | {
|
|
52
|
+
readonly type: 'ended';
|
|
53
|
+
readonly seq: number;
|
|
54
|
+
readonly reason: AvailabilityEndReason;
|
|
55
|
+
readonly final: GroupAvailability;
|
|
56
|
+
};
|
|
57
|
+
export type AvailabilityListener = (observation: AvailabilityObservation) => void;
|
|
58
|
+
type EndedObservation = Extract<AvailabilityObservation, {
|
|
59
|
+
type: 'ended';
|
|
60
|
+
}>;
|
|
61
|
+
/**
|
|
62
|
+
* Fences raised in this client session, by group: a runtime built again for the group starts fenced from here, so a
|
|
63
|
+
* fence whose marker write failed never reads clear again in the same session (A-7). Cleared by a teardown purge and
|
|
64
|
+
* by a new adoption of the group (a join or a restore), which start the group over.
|
|
65
|
+
*/
|
|
66
|
+
export declare class SessionFences {
|
|
67
|
+
#private;
|
|
68
|
+
/** Records `groupId`'s first fence of the session (a later one never replaces it). */
|
|
69
|
+
record(groupId: string, fence: Error): void;
|
|
70
|
+
get(groupId: string): Error | undefined;
|
|
71
|
+
causeOf(groupId: string): FenceCause | undefined;
|
|
72
|
+
clear(groupId: string): void;
|
|
73
|
+
}
|
|
74
|
+
/** The per-client part: the session's fences and whether the client's account lease ended (A-5, A-6). */
|
|
75
|
+
export interface ClientAvailability {
|
|
76
|
+
readonly sessionFences: SessionFences;
|
|
77
|
+
leaseEnded: boolean;
|
|
78
|
+
/**
|
|
79
|
+
* The client-wide end that came first (`no-lease` or `disposed`), recorded before any runtime's `ended` is
|
|
80
|
+
* delivered: a subscription made afterwards — even from inside a listener of that very close — ends with it.
|
|
81
|
+
*/
|
|
82
|
+
ended: Extract<AvailabilityEndReason, 'no-lease' | 'disposed'> | undefined;
|
|
83
|
+
/** The client's live runtimes (the registry's): what a lease end observed on one group closes. */
|
|
84
|
+
readonly runtimes: () => Iterable<GroupRuntime>;
|
|
85
|
+
}
|
|
86
|
+
export declare function createClientAvailability(runtimes?: () => Iterable<GroupRuntime>): ClientAvailability;
|
|
87
|
+
/** The per-runtime state (GroupRuntime fields). */
|
|
88
|
+
export interface RuntimeAvailability {
|
|
89
|
+
readonly availabilityListeners: Set<AvailabilitySubscription>;
|
|
90
|
+
/** The `seq` of the last observation produced (the current snapshot's, or the `ended`'s); 0 before the first. */
|
|
91
|
+
availabilitySeq: number;
|
|
92
|
+
/** The snapshot last published (what a new subscriber's initial observation carries). */
|
|
93
|
+
availabilityLast: GroupAvailability | undefined;
|
|
94
|
+
/** Set once the subscriptions ended: every later subscriber gets exactly this `ended`, and nothing more. */
|
|
95
|
+
availabilityEnded: EndedObservation | undefined;
|
|
96
|
+
readonly availabilityClient: ClientAvailability;
|
|
97
|
+
}
|
|
98
|
+
/** The inputs {@link availabilityFrom} decides on — read off a runtime by {@link availabilityOf}. */
|
|
99
|
+
export interface AvailabilityFacts {
|
|
100
|
+
readonly fence: Error | undefined;
|
|
101
|
+
readonly caughtUp: boolean;
|
|
102
|
+
readonly sendGateOpen: boolean;
|
|
103
|
+
readonly removedFromGroup: boolean;
|
|
104
|
+
readonly disbanded: boolean;
|
|
105
|
+
readonly leaseLive: boolean;
|
|
106
|
+
}
|
|
107
|
+
/** Pure: the availability the facts describe. */
|
|
108
|
+
export declare function availabilityFrom(facts: AvailabilityFacts): GroupAvailability;
|
|
109
|
+
/** The runtime's current facts. */
|
|
110
|
+
export declare function factsOf(rt: GroupRuntime): AvailabilityFacts;
|
|
111
|
+
/** The runtime's current availability (pure over {@link factsOf}). */
|
|
112
|
+
export declare function availabilityOf(rt: GroupRuntime): GroupAvailability;
|
|
113
|
+
/**
|
|
114
|
+
* One live subscription: its own FIFO of observations not yet delivered. Every observation is enqueued to every live
|
|
115
|
+
* subscription before any of them is drained, and a subscription's drain is non-reentrant (a publish or close raised
|
|
116
|
+
* from inside its listener only enqueues; the outer drain delivers it next). So each listener receives every change in
|
|
117
|
+
* `seq` order, then at most one `ended`, and nothing after it — whatever the listeners do from inside their callbacks.
|
|
118
|
+
*/
|
|
119
|
+
export interface AvailabilitySubscription {
|
|
120
|
+
readonly listener: AvailabilityListener;
|
|
121
|
+
readonly queue: AvailabilityObservation[];
|
|
122
|
+
draining: boolean;
|
|
123
|
+
/** The `ended` was enqueued: nothing more is ever enqueued. */
|
|
124
|
+
endQueued: boolean;
|
|
125
|
+
/** Unsubscribed: the queue is discarded and nothing more is delivered. */
|
|
126
|
+
unsubscribed: boolean;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Re-reads the runtime's facts and, when the snapshot changed, delivers it to every live listener with the next
|
|
130
|
+
* `seq`. A no-op once the subscriptions ended. Synchronous; never throws.
|
|
131
|
+
*/
|
|
132
|
+
export declare function publishAvailability(rt: GroupRuntime): void;
|
|
133
|
+
/**
|
|
134
|
+
* Subscribes `listener` to the group's availability (`MarmotGroup.observeAvailability`): the current snapshot is
|
|
135
|
+
* delivered synchronously, before this returns, then every change. After the subscriptions ended — or once the
|
|
136
|
+
* client's account lease ended — the listener gets the one `ended` and nothing more. The returned function
|
|
137
|
+
* unsubscribes (idempotent); no callback reaches the listener after it. What is delivered before this returns runs in
|
|
138
|
+
* the caller's re-entrancy frame (see {@link deliver}); every later change runs detached.
|
|
139
|
+
*/
|
|
140
|
+
export declare function observeAvailability(rt: GroupRuntime, listener: AvailabilityListener): () => void;
|
|
141
|
+
/**
|
|
142
|
+
* Ends the runtime's availability subscriptions (A-3): exactly one `ended` with `reason` to every listener, whose
|
|
143
|
+
* `final` is the current snapshot made not writable (a fenced group stays fenced in it). Idempotent: a later call is a
|
|
144
|
+
* no-op. Synchronous: awaits, schedules and stores nothing.
|
|
145
|
+
*/
|
|
146
|
+
export declare function closeAvailability(rt: GroupRuntime, reason: AvailabilityEndReason): void;
|
|
147
|
+
/**
|
|
148
|
+
* Ends every runtime's subscriptions in two phases: every runtime's `ended` is recorded (each isolated) before the
|
|
149
|
+
* returned function delivers any of them. So no listener of one runtime's `ended` can observe another runtime of the
|
|
150
|
+
* same close still open — a subscribe to it gets the stored `ended`, and a second close (a dispose raised from a
|
|
151
|
+
* `no-lease` listener) finds it already ended with the first reason.
|
|
152
|
+
*/
|
|
153
|
+
export declare function markAllAvailabilityEnded(runtimes: Iterable<GroupRuntime>, reason: AvailabilityEndReason): () => void;
|
|
154
|
+
/** {@link closeAvailability} for every runtime: all recorded first, then all delivered (see {@link markAllAvailabilityEnded}). */
|
|
155
|
+
export declare function closeAllAvailability(runtimes: Iterable<GroupRuntime>, reason: AvailabilityEndReason): void;
|
|
156
|
+
/**
|
|
157
|
+
* The client is being disposed: records the client-wide `disposed` end (unless the lease ended first) and every
|
|
158
|
+
* runtime's `ended/'disposed'` without delivering any; the returned function delivers them. Run the delivery once the
|
|
159
|
+
* runtimes are torn down, so a listener never sees a disposed client's group as still open.
|
|
160
|
+
*/
|
|
161
|
+
export declare function beginDisposeAvailability(client: ClientAvailability, runtimes: Iterable<GroupRuntime>): () => void;
|
|
162
|
+
/**
|
|
163
|
+
* Phase one of the client's account lease end (A-5): records the client-wide lease end (every later subscription of
|
|
164
|
+
* this client gets one immediate `ended/'no-lease'`) and every runtime's `ended/'no-lease'`, delivering nothing; the
|
|
165
|
+
* returned function delivers them. The caller settles its own lease-end consequences (the pending `synced()` waits)
|
|
166
|
+
* between the two, so a listener reacting to its `ended` (a `dispose()`) never pre-empts them. Synchronous; schedules
|
|
167
|
+
* no group work, timer, store access or transport call.
|
|
168
|
+
*/
|
|
169
|
+
export declare function beginLeaseEndAvailability(client: ClientAvailability, runtimes: Iterable<GroupRuntime>): () => void;
|
|
170
|
+
/**
|
|
171
|
+
* The client's account lease ended (A-5): every runtime's subscriptions end `no-lease`, and every later subscription
|
|
172
|
+
* of this client gets one immediate `ended/'no-lease'`. Every runtime is marked ended before any listener runs.
|
|
173
|
+
* Synchronous; schedules no group work, timer, store access or transport call.
|
|
174
|
+
*/
|
|
175
|
+
export declare function endAvailabilityForLease(client: ClientAvailability, runtimes: Iterable<GroupRuntime>): void;
|
|
176
|
+
/**
|
|
177
|
+
* A lost lease observed lazily on `rt` (a background retry meeting `no-lease`): the account lease is the client's, so
|
|
178
|
+
* this is phase one of the client-wide lease end of {@link beginLeaseEndAvailability} — the fallback for a store
|
|
179
|
+
* without `onLeaseEnded`. `rt` is closed too even when the registry does not hold it (yet). The returned function
|
|
180
|
+
* delivers the `ended` observations.
|
|
181
|
+
*/
|
|
182
|
+
export declare function beginLostLeaseAvailability(rt: GroupRuntime): () => void;
|