@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/types-CMBcFPhb.d.ts

@@ -0,0 +1,336 @@
+/**
+ * What a lease grants: the controller role, or one node's membership session.
+ *
+ * @public
+ */
+type CoordinatorLeaseKind = 'controller' | 'node-session';
+/**
+ * Stops a group watch when called.
+ *
+ * @public
+ */
+type CoordinatorWatchDisposer = () => void | Promise<void>;
+/**
+ * A time-limited claim one node holds, which lapses unless the node renews it.
+ *
+ * @public
+ */
+interface CoordinatorLease {
+    /** Identifier of the lease, which the holder renews and releases it by. */
+    id: string;
+    /** What the lease grants. */
+    kind: CoordinatorLeaseKind;
+    /** Cluster the lease belongs to. */
+    clusterId: string;
+    /** Identifier of the node holding it. */
+    holderId: string;
+    /** Milliseconds the lease lasts from each renewal. */
+    ttlMs: number;
+    /** Milliseconds since the Unix epoch, taken when the lease was granted. */
+    grantedAtMs: number;
+    /** Milliseconds since the Unix epoch, after which the lease lapses. */
+    expiresAtMs: number;
+    /** Anything else the holder attached. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A node's bid for the controller lease.
+ *
+ * @public
+ */
+interface AcquireControllerLeaseInput {
+    /** Cluster the lease covers. */
+    clusterId: string;
+    /** Identifier the node claims the lease under. */
+    holderId: string;
+    /** Milliseconds the lease should last. */
+    ttlMs: number;
+    /** Anything else to record against the lease. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Whether the bid won the controller lease, and who holds it either way.
+ *
+ * @public
+ */
+type AcquireControllerLeaseResult = {
+    acquired: true;
+    lease: CoordinatorLease;
+} | {
+    acquired: false;
+    lease: CoordinatorLease | null;
+};
+/**
+ * Versions a node publishes so that the group refuses a peer it cannot work with.
+ *
+ * @public
+ */
+interface CoordinatorCompatibilityMetadata {
+    /** Version of the package the node runs. */
+    packageVersion?: string;
+    /** Version of the specification the node implements. */
+    specVersion?: string;
+    /** Version of the replication protocol the node speaks. */
+    protocolVersion?: string;
+}
+/**
+ * What a node tells the coordinator about itself when it joins.
+ *
+ * @public
+ */
+interface RegisterNodeSessionInput {
+    /** Cluster the node joins. */
+    clusterId: string;
+    /** Identifier of the node. */
+    nodeId: string;
+    /** Milliseconds the session lasts from each renewal. */
+    ttlMs: number;
+    /** Address clients reach this node at. */
+    endpoint?: string;
+    /** Replication groups the node serves. */
+    groupIds?: string[];
+    /** Whether the node holds a copy of the data. */
+    dataBearing?: boolean;
+    /** Whether the node counts towards majority. */
+    voting?: boolean;
+    /** Versions the node publishes. */
+    compatibility?: CoordinatorCompatibilityMetadata;
+    /** Anything else to record against the session. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One node's live membership of a cluster, which lapses when its lease does.
+ *
+ * @public
+ */
+interface CoordinatorNodeSession {
+    /** Cluster the node belongs to. */
+    clusterId: string;
+    /** Identifier of the node. */
+    nodeId: string;
+    /** Lease keeping this session alive. */
+    lease: CoordinatorLease;
+    /** Address clients reach this node at. */
+    endpoint?: string;
+    /** Replication groups the node serves. */
+    groupIds: string[];
+    /** Whether the node holds a copy of the data. */
+    dataBearing: boolean;
+    /** Whether the node counts towards majority. */
+    voting: boolean;
+    /** Versions the node published. */
+    compatibility?: CoordinatorCompatibilityMetadata;
+    /** Anything else recorded against the session. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The node a group currently names as its primary.
+ *
+ * @public
+ */
+interface CoordinatorPrimary {
+    /** Identifier of the primary. */
+    nodeId: string;
+    /** Address clients reach it at. */
+    endpoint?: string;
+}
+/**
+ * The group's shared record of who writes, who is in sync, and how far the
+ * data is durable. Failover reads and advances it.
+ *
+ * @public
+ */
+interface ReplicationGroupState {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Nodes that count towards majority. */
+    votingDataBearingNodeIds: string[];
+    /** The node currently named primary, or null when the group has none. */
+    currentPrimary: CoordinatorPrimary | null;
+    /** Term the current primary holds, which rises with each promotion. */
+    primaryTerm: bigint;
+    /** Change-log position a majority of voting nodes has durably stored. */
+    durabilityPointSeq: bigint;
+    /** Nodes the group counts as in sync. */
+    inSyncNodeIds: string[];
+    /** Nodes being taken out of service. */
+    drainingNodeIds: string[];
+    /** Nodes being rebuilt. */
+    repairingNodeIds: string[];
+    /** Nodes the group has quarantined. */
+    faultedNodeIds: string[];
+    /** Versions the group requires of its members. */
+    compatibility?: CoordinatorCompatibilityMetadata;
+    /** Milliseconds since the Unix epoch, taken at the last change to this state. */
+    updatedAtMs: number;
+}
+/**
+ * The group state to write, which seeds a new group or replaces an existing one.
+ *
+ * @public
+ */
+interface SetReplicationGroupStateInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Nodes that count towards majority. */
+    votingDataBearingNodeIds: string[];
+    /** The node to name primary, or null to leave the group without one. */
+    currentPrimary?: CoordinatorPrimary | null;
+    /** Term to record for that primary. */
+    primaryTerm?: bigint;
+    /** Change-log position a majority has durably stored. */
+    durabilityPointSeq?: bigint;
+    /** Nodes to record as in sync. */
+    inSyncNodeIds?: string[];
+    /** Nodes to record as being taken out of service. */
+    drainingNodeIds?: string[];
+    /** Nodes to record as being rebuilt. */
+    repairingNodeIds?: string[];
+    /** Nodes to record as quarantined. */
+    faultedNodeIds?: string[];
+    /** Versions the group requires of its members. */
+    compatibility?: CoordinatorCompatibilityMetadata;
+}
+/**
+ * Promotes a node only while the group is still at the term the caller read,
+ * so two candidates cannot both promote themselves.
+ *
+ * @public
+ */
+interface CompareAndAdvancePrimaryTermInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Term the caller last read. The promotion fails when the group has moved past it. */
+    expectedPrimaryTerm: bigint;
+    /** The node to promote. */
+    nextPrimary: CoordinatorPrimary;
+}
+/**
+ * Whether the promotion took effect, and the group state that resulted.
+ *
+ * @public
+ */
+interface CompareAndAdvancePrimaryTermResult {
+    /** True when the group moved to the next term under the named primary. */
+    advanced: boolean;
+    /** The group state as it now stands, or null when the group is absent. */
+    state: ReplicationGroupState | null;
+}
+/**
+ * Replaces the group's in-sync set, and optionally moves its durability point.
+ *
+ * @public
+ */
+interface UpdateInSyncSetInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Nodes to record as in sync. */
+    inSyncNodeIds: string[];
+    /** Change-log position a majority has durably stored. */
+    durabilityPointSeq?: bigint;
+}
+/**
+ * Adds one caught-up node to the in-sync set, naming the progress that earned it.
+ *
+ * @public
+ */
+interface AdmitNodeToInSyncSetInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Node to admit. */
+    nodeId: string;
+    /** Node whose changes it has applied. */
+    sourceNodeId: string;
+    /** Change-log position it has applied up to. */
+    appliedSeq: bigint;
+}
+/**
+ * Marks one node as being taken out of service, rebuilt, or quarantined.
+ *
+ * @public
+ */
+interface UpdateNodeMaintenanceInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Node whose state changes. */
+    nodeId: string;
+    /** Whether the node is being taken out of service. */
+    draining?: boolean;
+    /** Whether the node is being rebuilt. */
+    repairing?: boolean;
+    /** Whether the group quarantines the node. */
+    faulted?: boolean;
+}
+/**
+ * Asks the coordinator to promote whichever in-sync replica is safe to write.
+ *
+ * @public
+ */
+interface PromoteEligibleReplicaInput {
+    /** Cluster the group belongs to. */
+    clusterId: string;
+    /** Identifier of the group. */
+    groupId: string;
+    /** Nodes to pass over, such as the primary that has just failed. */
+    excludeNodeIds?: string[];
+}
+/**
+ * Receives the group state each time it changes.
+ *
+ * @public
+ */
+type ReplicationGroupWatcher = (state: ReplicationGroupState) => void;
+/**
+ * Stores primary authority, node sessions, group state, and the in-sync set
+ * outside the database nodes so that failover has a source of truth no single node
+ * owns. The package includes an etcd adapter; build your own to store this
+ * elsewhere.
+ *
+ * @public
+ */
+interface ClusterCoordinator {
+    /** Bids for the controller lease, and reports who holds it. */
+    tryAcquireControllerLease(input: AcquireControllerLeaseInput): Promise<AcquireControllerLeaseResult>;
+    /** Extends a lease, and reports false once it has already lapsed. */
+    renewLease(leaseId: string, ttlMs: number): Promise<boolean>;
+    /** Gives up a lease at once instead of waiting for it to lapse. */
+    releaseLease(leaseId: string): Promise<boolean>;
+    /** Records one node as a live member of the cluster. */
+    registerNodeSession(input: RegisterNodeSessionInput): Promise<CoordinatorNodeSession>;
+    /** Reads one node's session, and returns null once its lease has lapsed. */
+    getLiveNodeSession(clusterId: string, nodeId: string): Promise<CoordinatorNodeSession | null>;
+    /** Ends one node's membership at once. */
+    deregisterNodeSession(clusterId: string, nodeId: string): Promise<void>;
+    /** Writes the group's state, which seeds a new group or replaces an existing one. */
+    setReplicationGroupState(input: SetReplicationGroupStateInput): Promise<ReplicationGroupState>;
+    /** Reads the group's state, and returns null when the group is absent. */
+    getReplicationGroupState(clusterId: string, groupId: string): Promise<ReplicationGroupState | null>;
+    /** Calls back on each change to the group's state, and returns a function that stops the watch. */
+    watchReplicationGroup(clusterId: string, groupId: string, watcher: ReplicationGroupWatcher): CoordinatorWatchDisposer | Promise<CoordinatorWatchDisposer>;
+    /** Promotes a node only while the group is still at the term the caller read. */
+    compareAndAdvancePrimaryTerm(input: CompareAndAdvancePrimaryTermInput): Promise<CompareAndAdvancePrimaryTermResult>;
+    /** Replaces the group's in-sync set, and optionally moves its durability point. */
+    updateInSyncSet(input: UpdateInSyncSetInput): Promise<ReplicationGroupState | null>;
+    /** Adds one caught-up node to the in-sync set. */
+    admitNodeToInSyncSet(input: AdmitNodeToInSyncSetInput): Promise<ReplicationGroupState | null>;
+    /** Marks one node as being taken out of service, rebuilt, or quarantined. */
+    updateNodeMaintenance(input: UpdateNodeMaintenanceInput): Promise<ReplicationGroupState | null>;
+    /** Promotes whichever in-sync replica is safe to write. */
+    promoteEligibleReplica(input: PromoteEligibleReplicaInput): Promise<ReplicationGroupState>;
+    /** Releases whatever the coordinator holds open. */
+    close?(): Promise<void>;
+}
+
+export type { AcquireControllerLeaseInput as A, ClusterCoordinator as C, PromoteEligibleReplicaInput as P, RegisterNodeSessionInput as R, SetReplicationGroupStateInput as S, UpdateInSyncSetInput as U, AcquireControllerLeaseResult as a, CoordinatorNodeSession as b, ReplicationGroupState as c, ReplicationGroupWatcher as d, CoordinatorWatchDisposer as e, CompareAndAdvancePrimaryTermInput as f, CompareAndAdvancePrimaryTermResult as g, AdmitNodeToInSyncSetInput as h, UpdateNodeMaintenanceInput as i, CoordinatorCompatibilityMetadata as j, CoordinatorLease as k, CoordinatorPrimary as l };

package/dist/types-CjhxcjhA.d.ts

@@ -0,0 +1,123 @@
+/** A hybrid logical clock reading, decoded into its three parts.
+ * @public
+ */
+interface HLCTimestamp {
+    /** Wall-clock milliseconds since the Unix epoch. */
+    wallMs: number;
+    /** Counter that orders events sharing one wall-clock millisecond. */
+    logical: number;
+    /** Identifier of the node that took the reading, which breaks remaining ties. */
+    nodeId: string;
+}
+/** One replicated row change, or one replicated schema statement.
+ * @public
+ */
+interface ReplicationChange {
+    /** Table the change belongs to. */
+    table: string;
+    /** What the change does to the row, or 'ddl' for a schema statement. */
+    operation: 'insert' | 'update' | 'delete' | 'ddl';
+    /** Primary key of the changed row, encoded as a string. */
+    rowId: string;
+    /** Primary key of the changed row, by column. */
+    primaryKey: Record<string, unknown>;
+    /** Hybrid logical clock stamp the authoring node gave this change. */
+    hlc: string;
+    /** Identifier of the transaction that produced this change. */
+    txId: string;
+    /** Identifier of the node that authored the change. */
+    nodeId: string;
+    /** The row after the change, or null for a delete. */
+    newData: Record<string, unknown> | null;
+    /** The row before the change, or null for an insert. */
+    oldData: Record<string, unknown> | null;
+    /** The schema statement to replay, present only when the operation is 'ddl'. */
+    ddlStatement?: string;
+}
+/** A checksummed run of changes one node sends to another.
+ * @public
+ */
+interface ReplicationBatch {
+    /** Identifier of the node that sent the batch. */
+    sourceNodeId: string;
+    /** Identifier of this batch, which the receiver acknowledges. */
+    batchId: string;
+    /** Change-log position of the first change in the batch. */
+    fromSeq: bigint;
+    /** Change-log position of the last change in the batch. */
+    toSeq: bigint;
+    /** Lowest and highest hybrid logical clock stamps the batch carries. */
+    hlcRange: {
+        min: string;
+        max: string;
+    };
+    /** The changes themselves, in ascending order. */
+    changes: ReplicationChange[];
+    /** Checksum of the changes, which the receiver verifies before it applies them. */
+    checksum: string;
+    /** Identifier of the replication group the sender belongs to. */
+    groupId?: string;
+    /** Primary term the sender held when it built the batch. */
+    primaryTerm?: bigint;
+}
+/** The local and incoming versions of one row, handed to a conflict resolver.
+ * @public
+ */
+interface ConflictContext {
+    /** Table the row belongs to. */
+    table: string;
+    /** Primary key of the row, encoded as a string. */
+    rowId: string;
+    /** The change already applied locally, or null when the receiver recorded none. */
+    localChange: ReplicationChange | null;
+    /** The change that arrived from the sending node. */
+    remoteChange: ReplicationChange;
+    /** Hybrid logical clock stamp of the local version, or null when there is none. */
+    localHlc: string | null;
+    /** Hybrid logical clock stamp of the incoming version. */
+    remoteHlc: string;
+}
+/** What a conflict resolver decided to do with one row.
+ * @public
+ */
+interface ConflictResolution {
+    /** Whether to take the incoming row, keep the local one, or write the merged row. */
+    action: 'accept_remote' | 'keep_local' | 'merge';
+    /** The row to write, required when the action is 'merge'. */
+    mergedData?: Record<string, unknown>;
+}
+/** Resolves which version of a row wins when a receiver already holds that row.
+ * @public
+ */
+interface ConflictResolver {
+    /** Chooses between the local and the incoming version of one row. */
+    resolve(ctx: ConflictContext): ConflictResolution | Promise<ConflictResolution>;
+}
+/** What applying one batch of changes did.
+ * @public
+ */
+interface ApplyResult {
+    /** Number of changes the receiver wrote. */
+    applied: number;
+    /** Number of changes the receiver had already seen. */
+    skipped: number;
+    /** Number of rows that went through a conflict resolver. */
+    conflicts: number;
+    /** Tables the batch dropped, named so callers can stop watching them. */
+    droppedTables: string[];
+}
+/** What a source node reports about one table at the end of first sync, so the joiner can verify it.
+ * @public
+ */
+interface SyncTableManifest {
+    /** Name of the table. */
+    table: string;
+    /** Number of rows the source held in that table. */
+    rowCount: number;
+    /** Hash of every primary key in the table, in order. */
+    pkHash?: string;
+    /** Chained digest of the batches the source streamed for this table. */
+    batchDigest?: string;
+}
+
+export type { ApplyResult as A, ConflictResolver as C, HLCTimestamp as H, ReplicationBatch as R, SyncTableManifest as S, ConflictContext as a, ConflictResolution as b, ReplicationChange as c };