@naylence/runtime 0.3.14 → 0.3.16

package/dist/esm/naylence/fame/node/default-connection-retry-policy.js

@@ -0,0 +1,47 @@
+/**
+ * Environment variable for overriding max initial attempts.
+ */
+export const ENV_VAR_SESSION_MAX_INITIAL_ATTEMPTS = 'FAME_SESSION_MAX_INITIAL_ATTEMPTS';
+/**
+ * Default implementation of connection retry policy.
+ *
+ * Before first successful attach:
+ * - Respects maxInitialAttempts configuration
+ * - Uses exponential backoff with jitter
+ *
+ * After first successful attach:
+ * - Always retries (unlimited) to maintain connection
+ * - Resets backoff if connection was stable for >10 seconds
+ */
+export class DefaultConnectionRetryPolicy {
+    constructor(options = {}) {
+        // Check for environment variable override
+        const envValue = typeof process !== 'undefined'
+            ? process.env?.[ENV_VAR_SESSION_MAX_INITIAL_ATTEMPTS]
+            : undefined;
+        if (envValue !== undefined && envValue !== '') {
+            const parsed = parseInt(envValue, 10);
+            this.maxInitialAttempts = isNaN(parsed) ? (options.maxInitialAttempts ?? 1) : parsed;
+        }
+        else {
+            this.maxInitialAttempts = options.maxInitialAttempts ?? 1;
+        }
+    }
+    shouldRetry(context) {
+        // After first successful attach, always retry to maintain connection
+        if (context.hadSuccessfulAttach) {
+            return true;
+        }
+        // maxInitialAttempts = 0 means unlimited retries
+        if (this.maxInitialAttempts === 0) {
+            return true;
+        }
+        // Fail if we've exceeded the configured max attempts
+        return context.attemptNumber < this.maxInitialAttempts;
+    }
+    calculateRetryDelay(_context, baseDelay) {
+        // Add jitter to prevent thundering herd
+        const jitter = Math.random() * baseDelay;
+        return baseDelay + jitter;
+    }
+}

package/dist/esm/naylence/fame/node/factory-commons.js

@@ -1,5 +1,6 @@
 import { createResource } from '@naylence/factory';
 import { AdmissionClientFactory } from './admission/admission-client-factory.js';
+import { ConnectionRetryPolicyFactory, } from './connection-retry-policy-factory.js';
 import { DefaultNodeIdentityPolicy } from './default-node-identity-policy.js';
 import { NodeIdentityPolicyFactory, } from './node-identity-policy-factory.js';
 import { DefaultNodeAttachClient } from './admission/default-node-attach-client.js';
@@ -124,6 +125,7 @@ export async function makeCommonOptions(config, rawConfig) {
     const telemetryConfig = pickOption(config.telemetry ?? null, aliasRecord, 'trace_emitter', 'telemetry_config');
     const securityConfig = pickOption(config.security ?? null, aliasRecord, 'security_manager', 'security_profile');
     const identityPolicyConfig = pickOption(config.identityPolicy ?? null, aliasRecord, 'identity_policy', 'node_identity_policy');
+    const connectionRetryPolicyConfig = pickOption(config.connectionRetryPolicy ?? null, aliasRecord, 'connection_retry_policy', 'retry_policy');
     const publicUrl = pickString(config.publicUrl ?? null, aliasRecord, 'public_url') ?? null;
     const directParentUrl = pickString(config.directParentUrl ?? null, aliasRecord, 'direct_parent_url') ?? null;
     const hasParentFlag = config.hasParent || Boolean(aliasRecord.has_parent ?? false);
@@ -133,6 +135,7 @@ export async function makeCommonOptions(config, rawConfig) {
     const nodeMetaStore = await storageProvider.getKeyValueStore(NodeMetaRecord, NODE_META_NAMESPACE);
     const nodeMeta = await nodeMetaStore.get('self');
     const identityPolicy = await resolveNodeIdentityPolicy(identityPolicyConfig ?? null, expressionOptions);
+    const connectionRetryPolicy = await resolveConnectionRetryPolicy(connectionRetryPolicyConfig ?? null, expressionOptions);
     const admissionClient = await resolveAdmissionClient(admissionConfig ?? null, expressionOptions, identityPolicy ?? undefined);
     const hasParent = determineHasParent(hasParentFlag, directParentUrl, admissionClient);
     const replicaStickinessManager = await resolveReplicaStickinessManager(hasParent, requestedLogicals, expressionOptions);
@@ -201,6 +204,7 @@ export async function makeCommonOptions(config, rawConfig) {
         transportListeners,
         traceEmitter,
         identityPolicy: identityPolicy ?? undefined,
+        connectionRetryPolicy: connectionRetryPolicy ?? undefined,
     };
 }
 async function resolveNodeIdentityPolicy(config, options) {
@@ -214,6 +218,17 @@ async function resolveNodeIdentityPolicy(config, options) {
         return null;
     }
 }
+async function resolveConnectionRetryPolicy(config, options) {
+    try {
+        return await ConnectionRetryPolicyFactory.createConnectionRetryPolicy(config ?? undefined, cloneCreateOptions(options));
+    }
+    catch (error) {
+        logger.warning('connection_retry_policy_creation_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
 async function resolveStorageProvider(config, options) {
     if (config) {
         try {

package/dist/esm/naylence/fame/node/index.js

@@ -25,3 +25,7 @@ export { DefaultNodeIdentityPolicyFactory, } from './default-node-identity-polic
 export * from './token-subject-node-identity-policy.js';
 export { TokenSubjectNodeIdentityPolicyFactory, } from './token-subject-node-identity-policy-factory.js';
 export { NodeIdentityPolicyProfileFactory, } from './node-identity-policy-profile-factory.js';
+export * from './connection-retry-policy.js';
+export * from './connection-retry-policy-factory.js';
+export * from './default-connection-retry-policy.js';
+export { DefaultConnectionRetryPolicyFactory, } from './default-connection-retry-policy-factory.js';

package/dist/esm/naylence/fame/node/node-config.js

@@ -23,6 +23,7 @@ const FameNodeConfigSchemaInternal = z
     telemetry: z.unknown().optional().nullable(),
     requestedCapabilities: z.array(z.string()).optional(),
     identityPolicy: z.unknown().optional().nullable(),
+    connectionRetryPolicy: z.unknown().optional().nullable(),
 })
     .passthrough();
 export function normalizeFameNodeConfig(input) {
@@ -64,6 +65,9 @@ export function normalizeFameNodeConfig(input) {
         identityPolicy: parsed.identityPolicy === undefined
             ? null
             : parsed.identityPolicy,
+        connectionRetryPolicy: parsed.connectionRetryPolicy === undefined
+            ? null
+            : parsed.connectionRetryPolicy,
     };
     if (parsed.requestedCapabilities) {
         normalized.requestedCapabilities = coerceStringArray(parsed.requestedCapabilities);

package/dist/esm/naylence/fame/node/node-factory.js

@@ -38,6 +38,7 @@ export class NodeFactory extends NodeLikeFactory {
             nodeMetaStore: components.nodeMetaStore,
             transportListeners: components.transportListeners,
             defaultServiceConfigs: serviceConfigs,
+            connectionRetryPolicy: components.connectionRetryPolicy,
         });
         return node;
     }

package/dist/esm/naylence/fame/node/node.js

@@ -141,6 +141,8 @@ export class FameNode extends TaskSpawner {
         this._acceptedLogicals = new Set(acceptedLogicalsOption);
         const deliveryPolicyOption = resolveOption(options, 'deliveryPolicy', 'delivery_policy');
         this._deliveryPolicy = deliveryPolicyOption ?? null;
+        const connectionRetryPolicyOption = resolveOption(options, 'connectionRetryPolicy', 'connection_retry_policy');
+        this._connectionRetryPolicy = connectionRetryPolicyOption ?? null;
         const admissionClientOption = resolveOption(options, 'admissionClient', 'admission_client');
         this._admissionClient = admissionClientOption ?? null;
         const attachClientOption = resolveOption(options, 'attachClient', 'attach_client');
@@ -270,6 +272,7 @@ export class FameNode extends TaskSpawner {
             onAttach: (info, connector) => this.handleAttach(info, connector),
             onEpochChange: (epoch) => this.handleEpochChange(epoch),
             admissionClient: this._admissionClient,
+            retryPolicy: this._connectionRetryPolicy,
         });
         this._sessionManager = manager;
         await manager.start();

package/dist/esm/naylence/fame/node/upstream-session-manager.js

@@ -82,6 +82,7 @@ function normalizeOptions(options) {
     const onEpochChangeValue = pickOption(record, 'onEpochChange', 'on_epoch_change');
     const onEpochChange = typeof onEpochChangeValue === 'function' ? onEpochChangeValue : undefined;
     const admissionClient = pickOption(record, 'admissionClient', 'admission_client');
+    const retryPolicy = pickOption(record, 'retryPolicy', 'retry_policy');
     return {
         node,
         attachClient,
@@ -93,6 +94,7 @@ function normalizeOptions(options) {
         onAttach: validatedOnAttach,
         onEpochChange,
         admissionClient: admissionClient ?? undefined,
+        retryPolicy: retryPolicy ?? undefined,
     };
 }
 export class UpstreamSessionManager extends TaskSpawner {
@@ -112,6 +114,7 @@ export class UpstreamSessionManager extends TaskSpawner {
         this.hadSuccessfulAttach = false;
         this.lastConnectorState = null;
         this.connectEpoch = 0;
+        this.initialAttempts = 0;
         this._visibilityHandler = null;
         const options = normalizeOptions(optionsInput);
         this.node = options.node;
@@ -125,8 +128,11 @@ export class UpstreamSessionManager extends TaskSpawner {
         this.admissionClient =
             options.admissionClient ?? options.node.admissionClient;
         this.wrappedHandler = this.makeHeartbeatEnabledHandler(options.inboundHandler);
+        // Store the connection retry policy (can be null, in which case default behavior applies)
+        this.connectionRetryPolicy = options.retryPolicy ?? null;
         logger.debug('created_upstream_session_manager', {
             target_system_id: this.targetSystemId,
+            has_retry_policy: this.connectionRetryPolicy !== null,
         });
     }
     get systemId() {
@@ -242,11 +248,14 @@ export class UpstreamSessionManager extends TaskSpawner {
     }
     async fsmLoop() {
         let delay = UpstreamSessionManager.BACKOFF_INITIAL;
+        this.initialAttempts = 0;
         while (!this.stopEvent.isSet()) {
             const startTime = Date.now();
+            this.initialAttempts += 1;
             try {
                 await this.connectCycle();
                 delay = UpstreamSessionManager.BACKOFF_INITIAL;
+                this.initialAttempts = 0; // Reset on success
             }
             catch (error) {
                 // Reset backoff if the connection was alive for more than 10 seconds
@@ -256,13 +265,17 @@ export class UpstreamSessionManager extends TaskSpawner {
                 if (error instanceof TaskCancelledError) {
                     throw error;
                 }
+                // Determine if we should fail-fast or retry
+                const shouldFailFast = this.shouldFailFastOnError(error);
                 if (error instanceof FameTransportClose ||
                     error instanceof FameConnectError) {
                     logger.warning('upstream_link_closed', {
                         error: error.message,
-                        will_retry: true,
+                        will_retry: !shouldFailFast,
+                        attempt: this.initialAttempts,
+                        has_retry_policy: this.connectionRetryPolicy !== null,
                     });
-                    if (!this.hadSuccessfulAttach && error instanceof FameConnectError) {
+                    if (shouldFailFast && error instanceof FameConnectError) {
                         throw error;
                     }
                 }
@@ -277,11 +290,13 @@ export class UpstreamSessionManager extends TaskSpawner {
                     else {
                         logger.warning('upstream_link_closed', {
                             error: err.message,
-                            will_retry: true,
+                            will_retry: !shouldFailFast,
+                            attempt: this.initialAttempts,
+                            has_retry_policy: this.connectionRetryPolicy !== null,
                             exc_info: true,
                         });
                     }
-                    if (!this.hadSuccessfulAttach) {
+                    if (shouldFailFast) {
                         throw error;
                     }
                 }
@@ -289,52 +304,77 @@ export class UpstreamSessionManager extends TaskSpawner {
             }
         }
     }
+    /**
+     * Determine whether to fail immediately or continue retrying.
+     * Returns true if we should throw the error instead of retrying.
+     */
+    shouldFailFastOnError(error) {
+        // If no policy is configured, use legacy behavior (fail-fast after first attempt)
+        if (!this.connectionRetryPolicy) {
+            // After first successful attach, always retry (existing behavior)
+            if (this.hadSuccessfulAttach) {
+                return false;
+            }
+            // Without a policy, fail on first error
+            return true;
+        }
+        // Delegate decision to the policy
+        const shouldRetry = this.connectionRetryPolicy.shouldRetry({
+            hadSuccessfulAttach: this.hadSuccessfulAttach,
+            attemptNumber: this.initialAttempts,
+            error,
+        });
+        return !shouldRetry;
+    }
     async applyBackoff(delay) {
         const jitter = Math.random() * delay;
-        await this.sleepWithStop(delay + jitter);
+        const wasWoken = await this.sleepWithStop(delay + jitter);
+        // If sleep was interrupted by visibility change (user returned to tab),
+        // reset backoff to initial delay for immediate retry with fresh backoff
+        if (wasWoken) {
+            logger.debug('backoff_reset_on_visibility_change', {
+                previous_delay: delay,
+                new_delay: UpstreamSessionManager.BACKOFF_INITIAL,
+            });
+            return UpstreamSessionManager.BACKOFF_INITIAL;
+        }
         return Math.min(delay * 2, UpstreamSessionManager.BACKOFF_CAP);
     }
+    /**
+     * Sleep for the specified duration, but can be interrupted by stop or wake events.
+     * @returns true if interrupted by wake event (e.g., visibility change), false otherwise
+     */
     async sleepWithStop(delaySeconds) {
         if (delaySeconds <= 0) {
-            return;
-        }
-        // If the document is visible, cap the backoff delay to improve UX
-        // This ensures that if the user is watching, we retry quickly (e.g. 1s)
-        // instead of waiting for the full exponential backoff (up to 30s).
-        let effectiveDelay = delaySeconds;
-        if (typeof document !== 'undefined' &&
-            document.visibilityState === 'visible') {
-            effectiveDelay = Math.min(delaySeconds, 1.0);
-            if (effectiveDelay < delaySeconds) {
-                logger.debug('sleep_reduced_document_visible', {
-                    original: delaySeconds,
-                    new: effectiveDelay,
-                });
-            }
+            return false;
         }
+        // Check if wake event is already set (e.g., visibility just changed)
         if (this.wakeEvent.isSet()) {
             this.wakeEvent.clear();
-            return;
+            logger.debug('sleep_skipped_wake_event_pending');
+            return true;
         }
         let timeout;
         const sleepPromise = new Promise((resolve) => {
             timeout = setTimeout(() => {
                 timeout = undefined;
                 resolve();
-            }, effectiveDelay * 1000);
+            }, delaySeconds * 1000);
         });
         await Promise.race([
             sleepPromise,
             this.stopEvent.wait(),
             this.wakeEvent.wait(),
         ]);
-        if (this.wakeEvent.isSet()) {
+        const wasWoken = this.wakeEvent.isSet();
+        if (wasWoken) {
             logger.debug('sleep_interrupted_by_wake_event');
             this.wakeEvent.clear();
         }
         if (timeout !== undefined) {
             clearTimeout(timeout);
         }
+        return wasWoken;
     }
     getNodeAttachGrant(connectionGrants) {
         if (!connectionGrants) {

package/dist/esm/naylence/fame/sentinel/sentinel.js

@@ -154,6 +154,7 @@ export class Sentinel extends FameNode {
         this.maxAttachTtlSec = opts.maxAttachTtlSec ?? null;
         this.requestedLogicals = opts.requestedLogicals ?? [];
         this.attachClient = opts.attachClient ?? null;
+        this.connectionRetryPolicy = opts.connectionRetryPolicy ?? null;
         this.nodeAttachFrameHandler = new NodeAttachFrameHandler({
             routingNode: this,
             routeManager: this.routeManager,
@@ -703,6 +704,7 @@ export class Sentinel extends FameNode {
             onAttach: (info, connector) => this.onNodeAttachToPeer(info, connector),
             onEpochChange: (epoch) => this.onEpochChange(epoch),
             onWelcome: async () => undefined,
+            retryPolicy: this.connectionRetryPolicy,
         });
         await sessionManager.start();
         const systemId = sessionManager.systemId;

package/dist/esm/node.js

@@ -1,10 +1,21 @@
 import './naylence/fame/connector/websocket-connector-node-ssl.js';
+import plugin from './plugin.js';
 // Ensure Node-specific registrations (storage, sqlite, etc.) happen before
 // the isomorphic exports are evaluated. Some factories (SQLite) must be
 // registered early so configuration parsing that happens during runtime
 // initialization can resolve the requested storage profiles.
 import './naylence/fame/storage/node-index.js'; // Side-effect: registers SQLite profiles
-// Auto-register the runtime plugin if we are in a Node.js environment
+// Always register the plugin directly. This ensures it is initialized even if
+// the dynamic import mechanism (used by FAME_PLUGINS) fails or is not used.
+(async () => {
+    try {
+        await plugin.register();
+    }
+    catch (err) {
+        console.error('[naylence-runtime] Failed to auto-register plugin:', err);
+    }
+})();
+// Auto-register the runtime plugin in FAME_PLUGINS for child processes
 if (typeof process !== 'undefined' && process.env) {
     const pluginName = '@naylence/runtime';
     const current = process.env.FAME_PLUGINS || '';

package/dist/esm/version.js

@@ -1,7 +1,7 @@
 // This file is auto-generated during build - do not edit manually
-// Generated from package.json version: 0.3.14
+// Generated from package.json version: 0.3.16
 /**
  * The package version, injected at build time.
  * @internal
  */
-export const VERSION = '0.3.14';
+export const VERSION = '0.3.16';