@ibgib/core-gib 0.1.22 → 0.1.25

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

@@ -1,18 +1,25 @@
 /**
- * @module SyncPeer_V1 witness class
+ * @module SyncPeer_V1 witness class for base class plumbing of sync peers.
+ *
+ * You are expected to implement concrete peer classes for concrete architecture.
  */
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
 import { SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
+import { SubjectWitness } from '../../common/pubsub/subject/subject-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 { InitializeSyncPeerOpts, SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness } from './sync-peer-types.mjs';
 import { LightWitnessBase_V1 } from '../../witness/light-witness-base-v1.mjs';
-import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
+import { newupSubject } from '../../common/pubsub/subject/subject-helper.mjs';
+import { validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
+import { getFromSpace } from '../../witness/space/space-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || true;
 const logalotControlDomain = true;
@@ -20,20 +27,22 @@ const lcControlDomain = '[ControlDomain]';
 
 /**
  * Abstract witness for talking to a Sync Peer (e.g. Remote Node or Local Simulator).
- * 
+ *
  * Takes a SyncSagaContext (Request) and returns a SyncSagaContext (Response).
- * 
+ *
  * Implements the core "Sync Protocol Transport" logic:
  * 1. Push Context & Dependencies (Sender -> Receiver)
  * 2. Send Request (RPC)
  * 3. Pull Response & Dependencies (Receiver -> Sender)
  */
-export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
-    implements SyncPeerWitness {
+export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts = InitializeSyncPeerOpts>
+    extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
+    implements SyncPeerWitness<TInitializeOpts> {
 
     protected lc: string = `[${SyncPeer_V1.name}]`;
 
-    abstract payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
+    public opts: TInitializeOpts | undefined;
+    public payloadIbGibsDomainReceived$!: SubjectWitness<IbGib_V1>;
 
     get classname(): string {
         if (!this.data) { throw new Error(`(UNEXPECTED) this.data falsy? (E: 1ab1841e9338b54f3aa615fa37024826)`); }
@@ -44,32 +53,156 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
     constructor(initialData: SyncPeerData_V1, initialRel8ns?: SyncPeerRel8ns_V1) {
         super(initialData, initialRel8ns);
     }
+
+    public async initialize(): Promise<void> {
+        this.payloadIbGibsDomainReceived$ = await newupSubject<IbGib_V1>();
+    }
+
+    /**
+     * base implementation just sets the opts property.
+     *
+     * override this in concrete classes for further initialization code
+     * specific to the sender.
+     *
+     * @see {@link SyncPeerWitness.opts}
+     */
+    public async initializeSender(opts: TInitializeOpts): Promise<void> {
+        const lc = `${this.lc}[${this.initializeSender.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 31bd5fda37c89fa37fbaf14daf5fe726)`); }
+            this.opts = opts;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    public setOptionalOpts(arg: Partial<TInitializeOpts>): void {
+        const lc = `${this.lc}[${this.setOptionalOpts.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: ae5ddbd3577db267f84743175a736626)`); }
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: 0dd4d6080a6e2f31d86cf4d86e11b826)`); }
+
+            if (logalot) { console.log(`${lc} updating opts. arg keys: ${Object.keys(arg)} (I: 452d78a558f8fc3468c8e2e68c70b226)`); }
+
+            this.opts = { ...this.opts, ...arg };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    // public setOptionalOpts({
+    //     senderTempSpace,
+    // }: {
+    //     senderTempSpace: IbGibSpaceAny,
+    // }): void {
+    //     const lc = `${this.lc}[${this.setOptionalOpts.name}]`;
+    //     try {
+    //         if (logalot) { console.log(`${lc} starting... (I: a17188953e38f07b1884e498ac490b26)`); }
+    //         if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: bdf00fe4b89b07ea78860d6ebe922e26)`); }
+
+    //         this.opts.senderTempSpace = senderTempSpace;
+    //     } catch (error) {
+    //         console.error(`${lc} ${extractErrorMsg(error)}`);
+    //         throw error;
+    //     } finally {
+    //         if (logalot) { console.log(`${lc} complete.`); }
+    //     }
+    // }
+
+    protected abstract ensureReceiverTempSpace(): Promise<IbGibSpaceAny>;
+
     /**
      * Witness the synchronization context (Send/Receive).
-     * 
+     *
+     * At this point in code, we are sending the context OUTGOING. The {@link context} should
+     * have a fully populated {@link SyncSagaContextIbGib_V1.sagaFrame}
+     *
      * @param arg The OUTGOING context (Request).
      * @returns The INCOMING context (Response), or undefined if failed/empty.
      */
-    async witness(arg: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+    override async witness(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
         const lc = `${this.lc}[${this.witness.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting...`); }
 
-            if (logalot) { console.log(`${lc} starting...`); }
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? Concrete class should have initialized sender opts by now. (E: 0b9e28287318fdf8bf9f5a6886a24826)`); }
+
+            // NOTE: There are two basic types of peers:
+            // * local-only (peer)
+            //   * this peer is both sender/receiver peer
+            //   * for local merges and relatively fast spaces
+            // * proxy to remote space
+            //   * this peer is both sender/receiver peer
+            //   * works directly with remote/outerspaces
+            //   * Less efficient over-the-wire xfer due to chatiness
+            // * symmetric node sender/receiver peers
+            //   * separate sender/receiver classes
+            //     * e.g., SyncPeerClient[Substrate]Sender_V1,
+            //       SyncPeerClient[Substrate]Receiver_V1
+            //   * More efficient over-the-wire xfer
+            //   * Most difficult to mentally model
+            //   * sender.witness does the pushing out
+            //     * what the sender/initiator's coordinator has a reference to
+            //   * receiver.witness does the coming in
+            //     * lives on a server/remote instance with its own coordinator
+            //       instance
+            //     * must do its own validation/authn/authz for possible MITM
+            //       issues
+            // The following is a sketch where some of these may be blurred
+
+            // persist the context, sagaframe, identity(s) ONLY in the receiver's durable space
+            // if sending domain ibgibs...
+            //   verify the domain ibgibs intrinsically.
+            //   persist the domain ibgibs in the receiver's temp space (push all addrs?)
+            //   await until all domain ibgibs are in receiver's temp space
+            // process the context with the receiver's coordinator to get a new response context
+            // analyze the response context
+            //   validate context intrinsically
+            //   validate return identity if present
+            // persist the response context's dependency graph (context, saga frame and msg(s), identities)
+            // if response has payload domain ibgibs,
+            //   spin off...
+            //     pull domain ibgibs to local temp space
+            //     publish domain ibgibs to observable
+            //     when all domain ibgibs are pulled, publish complete to the observable
+            // return resulting context ibgib (which the caller should get BEFORE the domain ibgibs observable completes)
+
+            // validate, authenticate, and authorize the context, sagaFrame, and identity(s)
+            const validationErrors = await validateContextAndSagaFrame({ context });
+            if (validationErrors.length > 0) {
+                throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
+            }
+            const authenticationErrors = await this.authenticateContext({ context });
+            if (authenticationErrors.length > 0) {
+                throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
+            }
+            const authorizationErrors = await this.authorizeContext({ context });
+            if (authorizationErrors.length > 0) {
+                throw new Error(`invalid context authorization. authorizationErrors: ${authorizationErrors} (E: 8ddc284a758cf10ba829334c1babb826)`);
+            }
 
-            // 1. PUSH: Ensure Request Data is available on Receiver
-            await this.pushContextGraph({ context: arg });
+            // at this point, we have a valid, authenticated, authorized context
 
             // 2. EXECUTE: Trigger Remote Processing
-            const response = await this.sendContextRequest(arg);
+            const response = await this.sendContextRequest(context);
 
             if (!response) {
                 if (logalot) { console.log(`${lc} No response from peer.`); }
                 return undefined;
             }
 
-            // 3. PULL: Ensure Response Data is available on Sender (Local)
-            await this.pullContextGraph({ context: response });
+            // at this point, all outgoing payload domain ibgibs have been sent.
+            // we have received the response context, wherein the sync saga
+            // frame/msg stone(s) and any keystones should be evolved. Depending
+            // on the concrete implementation, if there are domain ibgibs to
+            // receive, they may still be transferring. These will be published
+            // to this.payloadIbGibsDomainReceived$
 
             return response;
 
@@ -82,13 +215,25 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
     }
 
     /**
-     * Transmits the Context IbGib itself to the Peer.
+     * This is responsible for:
+     *
+     * * sending outgoing {@link context}, the sync saga frame and msg stone(s),
+     *   and identities...
+     * * AND sending OUTGOING domain ibgibs
+     *   {@link SyncSagaContextIbGib_V1.payloadIbGibsDomain}
+     * * getting back the other end's resultant context ibgib, sync saga frame
+     *   and msg stone(s), and identities in their entirety...
+     * * AND stream/receiving the RESPONSE payload domain ibgibs, publishing
+     *   these to this.payloadIbGibsDomainReceived$.
+     *
+     * So this returns the RESPONSE context, possibly BEFORE the RESPONSE domain
+     * ibgibs have been completely received/streamed. The coordinator is responsible
      */
     protected abstract sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
 
     /**
      * Pushes specific IbGib(s) (by address) from Local to Remote.
-     * 
+     *
      * Should NOT have to handle identifying if the remote already has it
      * (optimization), because the sync coordinator should be doing this in
      * its diffing algorithm.
@@ -100,145 +245,73 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
      */
     protected abstract pull(addrs: IbGibAddr[]): Promise<void>;
 
+
+
     /**
-     * Helper to orchestrate the PUSH of a Context's dependency graph.
+     * move to sync-peer-helpers.mts as a pure function?
      */
-    protected async pushContextGraph({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<void> {
-        const lc = `[${SyncPeer_V1.name}][pushContextGraph]`;
-
-        // A. Push Context Envelope
-        const contextAddr = getIbGibAddr({ ibGib: context });
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH Context Envelope -> ${contextAddr} (I: 3f4e5a6b7c8d9e0f)`); }
-        await this.push([contextAddr]);
-
-        // B. Push Saga Frame & Immediate Deps (Msg, Identity)
-        const frameAddr = context.rel8ns?.sagaFrame?.[0];
-        if (frameAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Saga Frame -> ${frameAddr} (I: 4a5b6c7d8e9f0a1b)`); }
-            await this.push([frameAddr]);
-            // We inspect the local frame to find its immediate deps
-            const frame = await this.getLocalIbGib(frameAddr);
-            if (frame) {
-                // Msg Stone
-                const msgAddrs = frame.rel8ns?.[SYNC_MSG_REL8N_NAME];
-                if (msgAddrs) {
-                    for (const addr of msgAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Msg Stone -> ${addr} (I: 5b6c7d8e9f0a1b2c)`); }
-                        await this.push([addr]);
-                    }
-                }
-                // Identity
-                const idAddrs = frame.rel8ns?.identity;
-                if (idAddrs) {
-                    for (const addr of idAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Identity -> ${addr} (I: 6c7d8e9f0a1b2c3d)`); }
-                        await this.push([addr]);
-                    }
-                }
-            }
-        }
+    protected async authenticateContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+        const lc = `${this.lc}[${this.authenticateContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 2677a482dfa873dcd1aa04a3031ff826)`); }
 
-        // C. Push Session Identity
-        const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
-        if (sessionKeystoneAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Session Keystone -> ${sessionKeystoneAddr} (I: 7d8e9f0a1b2c3d4e)`); }
-            await this.push([sessionKeystoneAddr]);
-        }
+            console.error(`${lc} NAG ERROR (NOT THROWN): not implemented. // todo: authenticate  (v1 must have this after we get merge logic workflow going) (E: bc3a78f2dab18ab64c36d055a4b50526)`);
 
-        // D. Push Payloads (Deep/Soft)
-        // For payloads, the Peer is just a transport. It doesn't know the structure.
-        // It relies on "push" handling the "deep" transfer if needed, or we explicitly iterate if we had a graph.
-        // But since we are "Witnessing", we usually assume "push(addr)" acts like "copy(addr, recursive=true)"?
-        // Or do we need to be explicit?
-        // User said: "payloads should be flat... sync coordinator is the one doing the heavy lifting".
-        // So we just push the addrs listed.
-
-        // 1. Control Payloads
-        // const controlAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_CONTROL];
-        // if (controlAddrs && controlAddrs.length > 0) {
-        //     if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL PAYLOADS (${controlAddrs.length}): ${controlAddrs.join(', ')} (I: 8e9f0a1b2c3d4e5f)`); }
-        //     for (const addr of controlAddrs) {
-        //         await this.push(addr);
-        //     }
-        // }
-
-        // 2. Domain Payloads
-        const domainAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN];
-        if (domainAddrs && domainAddrs.length > 0) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH DOMAIN PAYLOADS (${domainAddrs.length}): ${domainAddrs.join(', ')} (I: 9f0a1b2c3d4e5f6a)`); }
-            for (const addr of domainAddrs) {
-                await this.push([addr]);
-            }
+            return [];
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
         }
-
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH COMPLETE for context ${contextAddr} (I: a0b1c2d3e4f5a6b7)`); }
     }
 
     /**
-     * Helper to orchestrate the PULL of a Context's dependency graph.
+     * move to sync-peer-helpers.mts as a pure function?
      */
-    protected async pullContextGraph({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<void> {
-        const lc = `[${SyncPeer_V1.name}][pullContextGraph]`;
-
-        // A. Pull Context Envelope
-        const contextAddr = getIbGibAddr({ ibGib: context });
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL Context Envelope <- ${contextAddr} (I: b1c2d3e4f5a6b7c8)`); }
-        await this.pull([contextAddr]);
-
-        // B. Pull Saga Frame & Immediate Deps
-        const frameAddr = context.rel8ns?.sagaFrame?.[0];
-        if (frameAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Saga Frame <- ${frameAddr} (I: c2d3e4f5a6b7c8d9)`); }
-            await this.pull([frameAddr]);
-            // Inspect REMOTE frame? We need to have pulled it first.
-            const frame = await this.getLocalIbGib(frameAddr); // Should be local now
-            if (frame) {
-                const msgAddrs = frame.rel8ns?.[SYNC_MSG_REL8N_NAME];
-                if (msgAddrs) {
-                    for (const addr of msgAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Msg Stone <- ${addr} (I: d3e4f5a6b7c8d9e0)`); }
-                        await this.pull([addr]);
-                    }
-                }
-                const idAddrs = frame.rel8ns?.identity;
-                if (idAddrs) {
-                    for (const addr of idAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Identity <- ${addr} (I: e4f5a6b7c8d9e0f1)`); }
-                        await this.pull([addr]);
-                    }
-                }
-            }
-        }
+    protected async authorizeContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+        const lc = `${this.lc}[${this.authorizeContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 48c918b41ceec0cd489ca3b8819e6826)`); }
 
-        // C. Pull Session Identity
-        const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
-        if (sessionKeystoneAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Session Keystone <- ${sessionKeystoneAddr} (I: f5a6b7c8d9e0f1a2)`); }
-            await this.pull([sessionKeystoneAddr]);
-        }
+            console.error(`${lc} NAG ERROR (NOT THROWN): not implemented. authorize business logic (v1 must have this, but later when we are working on admin vs. student)(E: bc3a78f2dab18ab64c36d055a4b50526)`);
 
-        // D. Pull Payloads
-        // const controlAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_CONTROL];
-        // if (controlAddrs && controlAddrs.length > 0) {
-        //     if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL PAYLOADS (${controlAddrs.length}): ${controlAddrs.join(', ')} (I: a6b7c8d9e0f1a2b3)`); }
-        //     for (const addr of controlAddrs) {
-        //         await this.pull(addr);
-        //     }
-        // }
-        const domainAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN];
-        if (domainAddrs && domainAddrs.length > 0) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL DOMAIN PAYLOADS (${domainAddrs.length}): ${domainAddrs.join(', ')} (I: b7c8d9e0f1a2b3c4)`); }
-            for (const addr of domainAddrs) {
-                await this.pull([addr]);
-            }
+            return [];
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
         }
-
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL COMPLETE for context ${contextAddr} (I: c8d9e0f1a2b3c4d5)`); }
     }
 
     /**
      * Abstract accessor to get an IbGib from the Local space/store.
      * Needed for inspecting rela8ns during the graph walk.
+     *
+     * Default implementation simply looks in senderSpace
      */
-    protected abstract getLocalIbGib(addr: string): Promise<IbGib_V1 | undefined>;
+    protected async getLocalIbGib(addr: string): Promise<IbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.getLocalIbGib.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 27b248cb9801eeb2386b71485389a826)`); }
+
+            console.warn(`${lc} possibly a bottleneck here, getLocalIbGib only gets a single ibgib... (W: 2fd448a435480e6b128f6b8bcbef4826)`);
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: cfb9431f2fb851f24a6c88e80c3b3326)`); }
+
+            const resGet = await getFromSpace({ space: this.opts.senderSpace, addr });
+
+            if (resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1) {
+                const ibGib = resGet.ibGibs[0];
+                return ibGib;
+            } else {
+                throw new Error(`couldn't get addr (${addr}) from local space ${this.opts.senderSpace}. reason: ${resGet.errorMsg ?? 'unknown error (E: 926ef8bf4fcc299ab89dba34ea691a26)'} (E: d8a89807e471d3f8b938ab21df44cb26)`);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
 }