@ibgib/core-gib 0.1.23 → 0.1.25

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

@@ -1,9 +1,11 @@
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+
 import { KeystoneIbGib_V1 } from "../../keystone/keystone-types.mjs";
 import { SyncStage } from "../sync-constants.mjs";
 import { SyncMode, SyncConflictStrategy, } from "../sync-types.mjs";
 import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message-constants.mjs";
-import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import type { getDeltaDependencyGraph } from '../../common/other/graph-helper.mjs';
 
 export interface SyncSagaMessageIb_V1 {
     atom: typeof SYNC_SAGA_MSG_ATOM;
@@ -71,6 +73,50 @@ export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
     conflictStrategy?: SyncConflictStrategy;
 }
 
+/**
+ * When an endpoing doesn't have a timeline or some part of it, then this info 
+ * contains sufficient information for the other endpoint to know what addrs to
+ * send.
+ */
+export interface SyncSagaRequestAddrInfo {
+    /**
+     * We know this addr exists, but we don't have it. If we don't know anything
+     * about this timeline, then this will equal {@link tjpAddr}
+     */
+    addr: IbGibAddr;
+    /**
+     * if we're talking about an ibgib with a timeline (with ibgib.rel8ns.tjp),
+     * then this will be that timeline's addr (tjpAddr).
+     */
+    tjpAddr?: IbGibAddr;
+    /**
+     * If this is truthy, then we already have something from this timeline and
+     * this will be the latest addr in that timeline.
+     * 
+     * If falsy, then we are requesting the entire timeline be sent.
+     * 
+     * This is to be used to calculate the delta graph.
+     * @see {@link getDeltaDependencyGraph}
+     */
+    latestAddrAlreadyHave?: IbGibAddr;
+}
+
+/**
+ * when one endpoint says "hey, i have these that you need", they create this.
+ */
+export interface SyncSagaPushOfferInfo {
+    /**
+     * all addrs to be pushed, should be the entire delta dependency graph.
+     * @see {@link getDeltaDependencyGraph}
+     */
+    addrs: IbGibAddr[];
+    /**
+     * if we're talking about an ibgib with a timeline (with ibgib.rel8ns.tjp),
+     * then this will be that timeline's addr (tjpAddr).
+     */
+    tjpAddr?: IbGibAddr;
+}
+
 export interface SyncSagaConflictInfo {
     tjpAddr: string;
     /**
@@ -98,8 +144,8 @@ export interface SyncSagaConflictInfo {
 
 export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.ack;
-    deltaReqAddrs: string[];
-    pushOfferAddrs: string[];
+    deltaRequestAddrInfos: SyncSagaRequestAddrInfo[];
+    pushOfferInfos: SyncSagaPushOfferInfo[];
     /**
      * Map of group keys (TJP addr/constant addr) to list of known addresses
      * in that timeline.
@@ -113,8 +159,14 @@ export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
      * it needs all of the dependencies of A^5 (including A^4), but it does
      * NOT need to send A^0-A^3 (and dependencies) because receiver already has
      * these.
+     * 
+     * ## notes
+     * 
+     * I dislike this name in my rewrite/cleanup of this algorithm. However, I'm
+     * keeping it and am using it right now in handleInitFrame for including
+     * the receiver's latest addr/tip for the deltaReqAddrs. But really, I should 
      */
-    knowledgeVector?: { [tjpAddr: string]: string[] };
+    // knowledgeVector?: { [tjpAddr: string]: string[] };
     /**
      * List of identified conflicts.
      * 

package/src/sync/sync-types.mts

@@ -34,18 +34,19 @@ export function isValidSyncMode(mode: string): mode is SyncMode {
 // #region SyncConflictStrategy
 export const SYNC_CONFLICT_STRATEGY_ABORT = 'abort';
 export const SYNC_CONFLICT_STRATEGY_OPTIMISTIC = 'optimistic';
-export const SYNC_CONFLICT_STRATEGY_MANUAL = 'manual';
+// export const SYNC_CONFLICT_STRATEGY_MANUAL = 'manual'; // not implemented yet
 export type SyncConflictStrategy =
     | typeof SYNC_CONFLICT_STRATEGY_ABORT
     | typeof SYNC_CONFLICT_STRATEGY_OPTIMISTIC
-    | typeof SYNC_CONFLICT_STRATEGY_MANUAL;
+    // | typeof SYNC_CONFLICT_STRATEGY_MANUAL // not implemented yet
+    ;
 /**
  * @see {@link SyncOptions.conflictStrategy}
  */
 export const SyncConflictStrategy = {
     abort: SYNC_CONFLICT_STRATEGY_ABORT,
     optimistic: SYNC_CONFLICT_STRATEGY_OPTIMISTIC,
-    manual: SYNC_CONFLICT_STRATEGY_MANUAL,
+    // manual: SYNC_CONFLICT_STRATEGY_MANUAL, // not implemented yet
 } satisfies { [key in SyncConflictStrategy]: SyncConflictStrategy };
 export const SYNC_CONFLICT_STRATEGY_VALID_VALUES = Object.values(SyncConflictStrategy);
 export function isValidSyncConflictStrategy(strategy: string): strategy is SyncConflictStrategy {
@@ -53,15 +54,47 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
 }
 // #endregion SyncConflictStrategy
 
-/**
- * Result of handling a saga frame.
- * Separates control and domain payloads.
- */
-export interface HandleSagaFrameResult {
+export interface NextSagaFrameInfo_Frame {
     frame: SyncIbGib_V1;
     payloadIbGibsDomain?: IbGib_V1[];
     conflictInfos?: SyncSagaConflictInfo;
+    responseWasNull: undefined;
+}
+export interface NextSagaFrameInfo_Null {
+    frame: never;
+    payloadIbGibsDomain?: never;
+    conflictInfos?: never;
+    responseWasNull: true;
+}
+/**
+ * Result of handling a saga frame.
+ *
+ * ## notes
+ *
+ * After commit, this may have been a null response, so `frame` will not be
+ * defined, thus the discriminated union type.
+ */
+export type NextSagaFrameInfo =
+    NextSagaFrameInfo_Frame | NextSagaFrameInfo_Null;
+
+
+export interface HandleSagaResponseContextResult_Base {
+    /**
+     * if truthy, handling saga context failed, else it succeeded.
+     */
+    errorMsg?: string;
+    /**
+     * inner handling of the frame itself
+     */
+    nextFrameInfo?: NextSagaFrameInfo;
+}
+export interface HandleSagaResponseContextResult_Frame extends HandleSagaResponseContextResult_Base {
+    nextFrameInfo: NextSagaFrameInfo;
+}
+export interface HandleSagaResponseContextResult_Error extends HandleSagaResponseContextResult_Base {
+    errorMsg: string;
 }
+export type HandleSagaResponseContextResult = HandleSagaResponseContextResult_Frame | HandleSagaResponseContextResult_Error;
 
 export interface SyncOptions {
     /**
@@ -70,7 +103,7 @@ export interface SyncOptions {
     peer: SyncPeerWitness;
     /**
      * The ibgibs we wish to sync.
-     * 
+     *
      * These should all exist in {@link source}
      */
     domainIbGibs: IbGib_V1[],
@@ -101,14 +134,14 @@ export interface SyncOptions {
     /**
      * How to handle conflicts when both Source and Dest have diverged on the
      * same timeline.
-     * 
+     *
      * @default 'abort'
      */
     conflictStrategy?: SyncConflictStrategy;
     /**
-     * If true, creates an ephemeral session identity for the sync process to 
+     * If true, creates an ephemeral session identity for the sync process to
      * secure the sync transaction itself.
-     * 
+     *
      * @default true
      */
     useSessionIdentity?: boolean;
@@ -122,7 +155,7 @@ export interface SyncSagaInfo {
 
     /**
      * Observable stream of context updates happening during the saga.
-     * 
+     *
      * Subscribe to this to receive real-time progress throughout the sync
      * process, whenever the sync ibgib is evolved (including when receiving a
      * response from the peer).