@ibgib/core-gib 0.1.12 → 0.1.14

package/src/sync/sync-peer/sync-peer-types.mts

@@ -0,0 +1,43 @@
+/**
+ * @module sync peer witness types
+ */
+
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextRel8ns_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
+import { Witness_V1 } from '../../witness/witness-types.mjs';
+
+/**
+ * Data for the SyncPeer witness.
+ */
+export interface SyncPeerData_V1 extends IbGibData_V1 {
+    // Add specific settings for Sync Peer if needed (e.g. timeout, retry policy)
+}
+
+/**
+ * Relations for the SyncPeer witness.
+ */
+export interface SyncPeerRel8ns_V1 extends IbGibRel8ns_V1 {
+}
+
+/**
+ * The SyncPeer witness IbGib.
+ */
+export interface SyncPeerIbGib_V1 extends IbGib_V1<SyncPeerData_V1, SyncPeerRel8ns_V1> { }
+
+/**
+ * The interface for the SyncPeer witness class.
+ * It witnesses a SyncSagaContext and returns a SyncSagaContext (Request -> Response).
+ */
+export interface SyncPeerWitness extends Witness_V1<
+    SyncSagaContextData_V1,
+    SyncSagaContextRel8ns_V1,
+    SyncSagaContextIbGib_V1, // Input
+    SyncSagaContextData_V1,
+    SyncSagaContextRel8ns_V1,
+    SyncSagaContextIbGib_V1, // Output
+    SyncPeerData_V1,
+    SyncPeerRel8ns_V1
+> {
+    witness(arg: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
+}

package/src/sync/sync-peer/sync-peer-v1.mts

@@ -0,0 +1,28 @@
+/**
+ * @module SyncPeer_V1 witness class
+ */
+
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { SyncSagaContextIbGib_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
+import { SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness } from './sync-peer-types.mjs';
+import { LightWitnessBase_V1 } from '../../witness/light-witness-base-v1.mjs';
+
+/**
+ * Abstract witness for talking to a Sync Peer (e.g. Remote Node or Local Simulator).
+ * 
+ * Takes a SyncSagaContext (Request) and returns a SyncSagaContext (Response).
+ */
+export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
+    implements SyncPeerWitness {
+
+    protected lc: string = `[${SyncPeer_V1.name}]`;
+
+    /**
+     * Witness the synchronization context (Send/Receive).
+     * 
+     * @param arg The OUTGOING context (Request).
+     * @returns The INCOMING context (Response), or undefined if failed/empty.
+     */
+    abstract witness(arg: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
+}

package/src/sync/sync-saga-context/sync-saga-context-constants.mts

@@ -0,0 +1,8 @@
+/**
+ * @module sync saga context constants
+ */
+
+/**
+ * Atom for the sync saga context ibgib.
+ */
+export const SYNC_SAGA_CONTEXT_ATOM = 'sync_sagacontext';

package/src/sync/sync-saga-context/sync-saga-context-helpers.mts

@@ -0,0 +1,147 @@
+/**
+ * @module sync saga context helpers
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1, } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { Ib } from '@ibgib/ts-gib/dist/types.mjs';
+
+import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
+import {
+    SyncSagaContextCmd, SyncSagaContextData_V1, SyncSagaContextIbGib_V1,
+    SyncSagaContextIb_V1, SyncSagaContextRel8ns_V1
+} from './sync-saga-context-types.mjs';
+
+/**
+ * Options for creating a SyncSagaContext ibgib.
+ */
+export interface CreateSyncSagaContextOptions {
+    /**
+     * Optional command string (e.g. 'process').
+     */
+    cmd?: SyncSagaContextCmd | string;
+    /**
+     * The main saga frame (Init, Ack, etc.).
+     */
+    sagaFrame?: IbGib_V1;
+    /**
+     * Dependency stones (messages).
+     */
+    msgs?: IbGib_V1[];
+    /**
+     * Session identity keystones.
+     */
+    sessionKeystones?: IbGib_V1[];
+    /**
+     * Authorization claims.
+     */
+    claims?: IbGib_V1[];
+    /**
+     * Payload addresses (strings) for bulk data.
+     */
+    payload?: string[];
+}
+
+/**
+ * Constructs the standard 'ib' string for a Sync Saga Context stone.
+ */
+export async function getSyncSagaContextIb({
+    data,
+}: {
+    data: SyncSagaContextData_V1,
+}): Promise<Ib> {
+    const lc = `[${getSyncSagaContextIb.name}]`;
+    try {
+        if (!data) { throw new Error(`data required (E: 839d82138c234b3e89582855594191fe)`); }
+        const cmd = data.cmd || 'default';
+        // sync_sagacontext cmd
+        const ib = [
+            SYNC_SAGA_CONTEXT_ATOM,
+            cmd
+        ].join(' ');
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Parses a standard Sync Saga Context 'ib' string.
+ */
+export async function parseSyncSagaContextIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<SyncSagaContextIb_V1> {
+    const lc = `[${parseSyncSagaContextIb.name}]`;
+    try {
+        const parts = ib.split(' ');
+        if (parts.length < 2) {
+            throw new Error(`Invalid sync saga context ib. Expected at least 2 parts [atom cmd]. Got ${parts.length}. (E: 8b06c88820c74f5fb9f21f148459422a)`);
+        }
+        const [atom, ...rest] = parts;
+        const cmd = rest.join(' '); // cmd might have spaces if it's not a strict enum? but usually single word key.
+
+        if (atom !== SYNC_SAGA_CONTEXT_ATOM) {
+            throw new Error(`Atom mismatch. Expected ${SYNC_SAGA_CONTEXT_ATOM}. Got ${atom}. (E: 67d71fc0f8d04840b178652309f471f5)`);
+        }
+
+        return { atom, cmd };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Creates a new SyncSagaContext ibGib stone.
+ * 
+ * @returns The context ibGib.
+ */
+export async function createSyncSagaContext({
+    cmd,
+    sagaFrame,
+    msgs,
+    sessionKeystones,
+    claims,
+    payload,
+}: CreateSyncSagaContextOptions): Promise<SyncSagaContextIbGib_V1> {
+
+    const data: SyncSagaContextData_V1 = {
+        cmd,
+    };
+
+    const rel8ns: SyncSagaContextRel8ns_V1 = {};
+
+    if (sagaFrame) {
+        rel8ns.sagaFrame = [getIbGibAddr(sagaFrame)];
+    }
+    if (msgs && msgs.length > 0) {
+        rel8ns.msgs = msgs.map(getIbGibAddr);
+    }
+    if (sessionKeystones && sessionKeystones.length > 0) {
+        rel8ns.sessionKeystone = sessionKeystones.map(getIbGibAddr);
+    }
+    if (claims && claims.length > 0) {
+        rel8ns.claims = claims.map(getIbGibAddr);
+    }
+    if (payload && payload.length > 0) {
+        rel8ns.payload = payload;
+    }
+
+    // Generate standard ib
+    const ib = await getSyncSagaContextIb({ data });
+
+    const contextIbGib = await Factory_V1.stone<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1>({
+        parentPrimitiveIb: SYNC_SAGA_CONTEXT_ATOM,
+        ib,
+        data,
+        rel8ns,
+    });
+
+    return contextIbGib as SyncSagaContextIbGib_V1;
+}

package/src/sync/sync-saga-context/sync-saga-context-types.mts

@@ -0,0 +1,80 @@
+/**
+ * @module sync saga context types
+ */
+
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+// #region SyncSagaContextCmd
+/**
+ * Commands for the Sync Saga Context.
+ */
+export type SyncSagaContextCmd =
+    | 'process'
+    | 'ping';
+export const SyncSagaContextCmd = {
+    process: 'process' as SyncSagaContextCmd,
+    ping: 'ping' as SyncSagaContextCmd,
+} satisfies { [key in SyncSagaContextCmd]: SyncSagaContextCmd };
+export const SYNC_SAGA_CONTEXT_CMD_VALID_VALUES = Object.values(SyncSagaContextCmd);
+export function isValidSyncSagaContextCmd(cmd: string): cmd is SyncSagaContextCmd {
+    return SYNC_SAGA_CONTEXT_CMD_VALID_VALUES.includes(cmd as SyncSagaContextCmd);
+}
+// #endregion SyncSagaContextCmd
+
+export interface SyncSagaContextIb_V1 {
+    atom: string; // SYNC_SAGA_CONTEXT_ATOM
+    cmd: SyncSagaContextCmd | string;
+}
+
+/**
+ * Data payload for the Sync Saga Context.
+ */
+export interface SyncSagaContextData_V1 extends IbGibData_V1 {
+    /**
+     * Contextual command or metadata for the transport layer.
+     * e.g. "process", "ping".
+     */
+    cmd?: SyncSagaContextCmd | string;
+}
+
+/**
+ * Relationships for the Sync Saga Context.
+ * Contains the "Tip" saga frame and all necessary dependency stones/identities/claims.
+ */
+export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
+    /**
+     * The primary Saga Frame being transported (Init, Ack, Delta, etc.).
+     * 0..1 (Optional only if trivial ping or strict metadata update)
+     */
+    sagaFrame?: string[]; // [addr]
+
+    /**
+     * Message stones associated with this context (e.g. Init payload stone).
+     * These provide the data payload for the saga frame.
+     */
+    msgs?: string[];
+
+    /**
+     * The Ephemeral Session Keystone Identity used for this saga.
+     * Required for validating the saga frame signature.
+     */
+    sessionKeystone?: string[];
+
+    /**
+     * Authorization claims linking Session Key to a Primary Identity.
+     * Required for authorizing the session key.
+     */
+    claims?: string[];
+
+    /**
+     * Payload data (ibGibs) being transported in this context (e.g. for Delta stage).
+     * These are the actual stones/timelines being synced.
+     */
+    payload?: string[];
+}
+
+/**
+ * The SyncSagaContext is a full-fledged ibGib used as the payload
+ * between Sync Peers.
+ */
+export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1> { }