@naylence/runtime 0.3.15 → 0.3.16

package/dist/types/naylence/fame/factory-manifest.d.ts

@@ -4,7 +4,7 @@
  *
  * Provides the list of runtime factory modules for registration.
  */
-export declare const MODULES: readonly ["./connector/broadcast-channel-connector-factory.js", "./connector/broadcast-channel-listener-factory.js", "./connector/http-listener-factory.js", "./connector/http-stateless-connector-factory.js", "./connector/inpage-connector-factory.js", "./connector/inpage-listener-factory.js", "./connector/websocket-connector-factory.js", "./connector/websocket-listener-factory.js", "./delivery/at-least-once-delivery-policy-factory.js", "./delivery/at-most-once-delivery-policy-factory.js", "./delivery/delivery-profile-factory.js", "./fabric/in-process-fame-fabric-factory.js", "./node/admission/admission-profile-factory.js", "./node/admission/direct-admission-client-factory.js", "./node/admission/noop-admission-client-factory.js", "./node/admission/welcome-service-client-factory.js", "./node/default-node-identity-policy-factory.js", "./node/node-factory.js", "./node/node-identity-policy-profile-factory.js", "./node/token-subject-node-identity-policy-factory.js", "./placement/static-node-placement-strategy-factory.js", "./security/auth/bearer-token-header-auth-injection-strategy-factory.js", "./security/auth/default-authorizer-factory.js", "./security/auth/jwks-jwt-token-verifier-factory.js", "./security/auth/jwt-token-issuer-factory.js", "./security/auth/jwt-token-verifier-factory.js", "./security/auth/no-auth-injection-strategy-factory.js", "./security/auth/none-token-provider-factory.js", "./security/auth/noop-authorizer-factory.js", "./security/auth/noop-token-issuer-factory.js", "./security/auth/noop-token-verifier-factory.js", "./security/auth/oauth2-authorizer-factory.js", "./security/auth/oauth2-client-credentials-token-provider-factory.js", "./security/auth/oauth2-pkce-token-provider-factory.js", "./security/auth/query-param-auth-injection-strategy-factory.js", "./security/auth/shared-secret-authorizer-factory.js", "./security/auth/shared-secret-token-provider-factory.js", "./security/auth/shared-secret-token-verifier-factory.js", "./security/auth/static-token-provider-factory.js", "./security/auth/websocket-subprotocol-auth-injection-strategy-factory.js", "./security/credential/dev-fixed-key-credential-provider-factory.js", "./security/credential/env-credential-provider-factory.js", "./security/credential/none-credential-provider-factory.js", "./security/credential/prompt-credential-provider-factory.js", "./security/credential/secret-store-credential-provider-factory.js", "./security/credential/session-key-credential-provider-factory.js", "./security/credential/static-credential-provider-factory.js", "./security/default-security-manager-factory.js", "./security/encryption/noop-encryption-manager-factory.js", "./security/encryption/noop-secure-channel-manager-factory.js", "./security/keys/default-key-manager-factory.js", "./security/keys/in-memory-key-store-factory.js", "./security/keys/noop-key-validator-factory.js", "./security/node-security-profile-factory.js", "./security/policy/default-security-policy-factory.js", "./security/policy/no-security-policy-factory.js", "./security/signing/eddsa-envelope-signer-factory.js", "./security/signing/eddsa-envelope-verifier-factory.js", "./security/trust-store/noop-trust-store-provider-factory.js", "./sentinel/capability-aware-routing-policy-factory.js", "./sentinel/composite-routing-policy-factory.js", "./sentinel/hybrid-path-routing-policy-factory.js", "./sentinel/load-balancing/composite-load-balancing-strategy-factory.js", "./sentinel/load-balancing/hrw-load-balancing-strategy-factory.js", "./sentinel/load-balancing/load-balancing-profile-factory.js", "./sentinel/load-balancing/random-load-balancing-strategy-factory.js", "./sentinel/load-balancing/round-robin-load-balancing-strategy-factory.js", "./sentinel/load-balancing/sticky-load-balancing-strategy-factory.js", "./sentinel/routing-profile-factory.js", "./sentinel/sentinel-factory.js", "./sentinel/store/route-store-factory.js", "./stickiness/simple-load-balancer-stickiness-manager-factory.js", "./telemetry/noop-trace-emitter-factory.js", "./telemetry/open-telemetry-trace-emitter-factory.js", "./telemetry/trace-emitter-profile-factory.js", "./welcome/default-welcome-service-factory.js"];
+export declare const MODULES: readonly ["./connector/broadcast-channel-connector-factory.js", "./connector/broadcast-channel-listener-factory.js", "./connector/http-listener-factory.js", "./connector/http-stateless-connector-factory.js", "./connector/inpage-connector-factory.js", "./connector/inpage-listener-factory.js", "./connector/websocket-connector-factory.js", "./connector/websocket-listener-factory.js", "./delivery/at-least-once-delivery-policy-factory.js", "./delivery/at-most-once-delivery-policy-factory.js", "./delivery/delivery-profile-factory.js", "./fabric/in-process-fame-fabric-factory.js", "./node/admission/admission-profile-factory.js", "./node/admission/direct-admission-client-factory.js", "./node/admission/noop-admission-client-factory.js", "./node/admission/welcome-service-client-factory.js", "./node/default-connection-retry-policy-factory.js", "./node/default-node-identity-policy-factory.js", "./node/node-factory.js", "./node/node-identity-policy-profile-factory.js", "./node/token-subject-node-identity-policy-factory.js", "./placement/static-node-placement-strategy-factory.js", "./security/auth/bearer-token-header-auth-injection-strategy-factory.js", "./security/auth/default-authorizer-factory.js", "./security/auth/jwks-jwt-token-verifier-factory.js", "./security/auth/jwt-token-issuer-factory.js", "./security/auth/jwt-token-verifier-factory.js", "./security/auth/no-auth-injection-strategy-factory.js", "./security/auth/none-token-provider-factory.js", "./security/auth/noop-authorizer-factory.js", "./security/auth/noop-token-issuer-factory.js", "./security/auth/noop-token-verifier-factory.js", "./security/auth/oauth2-authorizer-factory.js", "./security/auth/oauth2-client-credentials-token-provider-factory.js", "./security/auth/oauth2-pkce-token-provider-factory.js", "./security/auth/query-param-auth-injection-strategy-factory.js", "./security/auth/shared-secret-authorizer-factory.js", "./security/auth/shared-secret-token-provider-factory.js", "./security/auth/shared-secret-token-verifier-factory.js", "./security/auth/static-token-provider-factory.js", "./security/auth/websocket-subprotocol-auth-injection-strategy-factory.js", "./security/credential/dev-fixed-key-credential-provider-factory.js", "./security/credential/env-credential-provider-factory.js", "./security/credential/none-credential-provider-factory.js", "./security/credential/prompt-credential-provider-factory.js", "./security/credential/secret-store-credential-provider-factory.js", "./security/credential/session-key-credential-provider-factory.js", "./security/credential/static-credential-provider-factory.js", "./security/default-security-manager-factory.js", "./security/encryption/noop-encryption-manager-factory.js", "./security/encryption/noop-secure-channel-manager-factory.js", "./security/keys/default-key-manager-factory.js", "./security/keys/in-memory-key-store-factory.js", "./security/keys/noop-key-validator-factory.js", "./security/node-security-profile-factory.js", "./security/policy/default-security-policy-factory.js", "./security/policy/no-security-policy-factory.js", "./security/signing/eddsa-envelope-signer-factory.js", "./security/signing/eddsa-envelope-verifier-factory.js", "./security/trust-store/noop-trust-store-provider-factory.js", "./sentinel/capability-aware-routing-policy-factory.js", "./sentinel/composite-routing-policy-factory.js", "./sentinel/hybrid-path-routing-policy-factory.js", "./sentinel/load-balancing/composite-load-balancing-strategy-factory.js", "./sentinel/load-balancing/hrw-load-balancing-strategy-factory.js", "./sentinel/load-balancing/load-balancing-profile-factory.js", "./sentinel/load-balancing/random-load-balancing-strategy-factory.js", "./sentinel/load-balancing/round-robin-load-balancing-strategy-factory.js", "./sentinel/load-balancing/sticky-load-balancing-strategy-factory.js", "./sentinel/routing-profile-factory.js", "./sentinel/sentinel-factory.js", "./sentinel/store/route-store-factory.js", "./stickiness/simple-load-balancer-stickiness-manager-factory.js", "./telemetry/noop-trace-emitter-factory.js", "./telemetry/open-telemetry-trace-emitter-factory.js", "./telemetry/trace-emitter-profile-factory.js", "./welcome/default-welcome-service-factory.js"];
 export type FactoryModuleSpec = (typeof MODULES)[number];
 export type FactoryModuleLoader = () => Promise<Record<string, unknown>>;
 export declare const MODULE_LOADERS: Record<FactoryModuleSpec, FactoryModuleLoader>;

package/dist/types/naylence/fame/node/connection-retry-policy-factory.d.ts

@@ -0,0 +1,20 @@
+import type { CreateResourceOptions, ResourceConfig } from '@naylence/factory';
+import { AbstractResourceFactory } from '@naylence/factory';
+import type { ConnectionRetryPolicy } from './connection-retry-policy.js';
+export declare const CONNECTION_RETRY_POLICY_FACTORY_BASE_TYPE = "ConnectionRetryPolicyFactory";
+export interface ConnectionRetryPolicyConfig extends ResourceConfig {
+    type: string;
+    /**
+     * Maximum number of connection attempts before giving up (before first successful attach).
+     * - `1` (default): Fail immediately on first error
+     * - `0`: Unlimited retries with exponential backoff
+     * - `N > 1`: Retry up to N times with exponential backoff
+     */
+    maxInitialAttempts?: number | string;
+    max_initial_attempts?: number | string;
+    [key: string]: unknown;
+}
+export declare abstract class ConnectionRetryPolicyFactory<C extends ConnectionRetryPolicyConfig = ConnectionRetryPolicyConfig> extends AbstractResourceFactory<ConnectionRetryPolicy, C> {
+    abstract create(config?: C | Record<string, unknown> | null, ...factoryArgs: unknown[]): Promise<ConnectionRetryPolicy>;
+    static createConnectionRetryPolicy<C extends ConnectionRetryPolicyConfig = ConnectionRetryPolicyConfig>(config?: C | Record<string, unknown> | null, options?: CreateResourceOptions): Promise<ConnectionRetryPolicy>;
+}

package/dist/types/naylence/fame/node/connection-retry-policy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Context provided to the connection retry policy for decision-making.
+ */
+export interface ConnectionRetryContext {
+    /**
+     * Whether a successful attach has occurred previously in this session.
+     */
+    hadSuccessfulAttach: boolean;
+    /**
+     * Number of attempts made so far (1-indexed, incremented before each attempt).
+     */
+    attemptNumber: number;
+    /**
+     * The error that caused the connection failure, if any.
+     */
+    error?: unknown;
+    /**
+     * Duration in milliseconds that the last connection was alive before failing.
+     */
+    connectionDurationMs?: number;
+}
+/**
+ * Policy for determining whether to retry upstream connection attempts.
+ *
+ * This policy is stateless - all state needed for decision-making is passed
+ * via the context parameter.
+ */
+export interface ConnectionRetryPolicy {
+    /**
+     * Determines whether to retry after a connection failure.
+     *
+     * @param context - Information about the current retry state
+     * @returns `true` if a retry should be attempted, `false` if the error should be thrown
+     */
+    shouldRetry(context: ConnectionRetryContext): boolean;
+    /**
+     * Calculates the delay before the next retry attempt.
+     *
+     * @param context - Information about the current retry state
+     * @param baseDelay - The base delay in seconds (may be adjusted by exponential backoff)
+     * @returns Delay in seconds before the next attempt (including any jitter)
+     */
+    calculateRetryDelay(context: ConnectionRetryContext, baseDelay: number): number;
+}

package/dist/types/naylence/fame/node/default-connection-retry-policy-factory.d.ts

@@ -0,0 +1,15 @@
+import { ConnectionRetryPolicyFactory, type ConnectionRetryPolicyConfig } from './connection-retry-policy-factory.js';
+import type { ConnectionRetryPolicy } from './connection-retry-policy.js';
+export interface DefaultConnectionRetryPolicyConfig extends ConnectionRetryPolicyConfig {
+    type: 'DefaultConnectionRetryPolicy';
+}
+export declare const FACTORY_META: {
+    readonly base: "ConnectionRetryPolicyFactory";
+    readonly key: "DefaultConnectionRetryPolicy";
+};
+export declare class DefaultConnectionRetryPolicyFactory extends ConnectionRetryPolicyFactory<DefaultConnectionRetryPolicyConfig> {
+    readonly type = "DefaultConnectionRetryPolicy";
+    readonly isDefault = true;
+    create(config?: DefaultConnectionRetryPolicyConfig | Record<string, unknown> | null): Promise<ConnectionRetryPolicy>;
+}
+export default DefaultConnectionRetryPolicyFactory;

package/dist/types/naylence/fame/node/default-connection-retry-policy.d.ts

@@ -0,0 +1,36 @@
+import type { ConnectionRetryContext, ConnectionRetryPolicy } from './connection-retry-policy.js';
+/**
+ * Environment variable for overriding max initial attempts.
+ */
+export declare const ENV_VAR_SESSION_MAX_INITIAL_ATTEMPTS = "FAME_SESSION_MAX_INITIAL_ATTEMPTS";
+/**
+ * Options for the default connection retry policy.
+ */
+export interface DefaultConnectionRetryPolicyOptions {
+    /**
+     * Maximum number of connection attempts before giving up (before first successful attach).
+     * - `1` (default): Fail immediately on first error
+     * - `0`: Unlimited retries with exponential backoff
+     * - `N > 1`: Retry up to N times with exponential backoff
+     *
+     * Can be overridden via FAME_SESSION_MAX_INITIAL_ATTEMPTS environment variable.
+     */
+    maxInitialAttempts?: number;
+}
+/**
+ * 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 declare class DefaultConnectionRetryPolicy implements ConnectionRetryPolicy {
+    readonly maxInitialAttempts: number;
+    constructor(options?: DefaultConnectionRetryPolicyOptions);
+    shouldRetry(context: ConnectionRetryContext): boolean;
+    calculateRetryDelay(_context: ConnectionRetryContext, baseDelay: number): number;
+}

package/dist/types/naylence/fame/node/factory-commons.d.ts

@@ -1,4 +1,5 @@
 import type { AdmissionClient } from './admission/admission-client.js';
+import type { ConnectionRetryPolicy } from './connection-retry-policy.js';
 import type { NodeIdentityPolicy } from './node-identity-policy.js';
 import { DefaultNodeAttachClient } from './admission/default-node-attach-client.js';
 import type { FameNodeConfig } from './node-config.js';
@@ -40,5 +41,6 @@ export interface CommonNodeComponents {
     transportListeners: TransportListener[];
     traceEmitter: TraceEmitter | null;
     identityPolicy?: NodeIdentityPolicy;
+    connectionRetryPolicy?: ConnectionRetryPolicy;
 }
 export declare function makeCommonOptions(config: FameNodeConfig, rawConfig?: Record<string, unknown> | null): Promise<CommonNodeComponents>;

package/dist/types/naylence/fame/node/index.d.ts

@@ -26,3 +26,7 @@ export { DefaultNodeIdentityPolicyFactory, DefaultNodeIdentityPolicyConfig, } fr
 export * from './token-subject-node-identity-policy.js';
 export { TokenSubjectNodeIdentityPolicyFactory, TokenSubjectNodeIdentityPolicyConfig, } from './token-subject-node-identity-policy-factory.js';
 export { NodeIdentityPolicyProfileFactory, NodeIdentityPolicyProfileConfig, } 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, DefaultConnectionRetryPolicyConfig, } from './default-connection-retry-policy-factory.js';

package/dist/types/naylence/fame/node/node-config.d.ts

@@ -1,4 +1,5 @@
 import type { AdmissionConfig } from './admission/admission-client-factory.js';
+import type { ConnectionRetryPolicyConfig } from './connection-retry-policy-factory.js';
 import type { NodeIdentityPolicyConfig } from './node-identity-policy-factory.js';
 import type { NodeLikeConfig } from './node-like-factory.js';
 import type { DeliveryPolicyConfig } from '../delivery/delivery-policy-config.js';
@@ -29,5 +30,6 @@ export type FameNodeConfig = NodeLikeConfig & {
     telemetry?: TraceEmitterConfig | Record<string, unknown> | null;
     requestedCapabilities?: string[];
     identityPolicy?: NodeIdentityPolicyConfig | Record<string, unknown> | null;
+    connectionRetryPolicy?: ConnectionRetryPolicyConfig | Record<string, unknown> | null;
 };
 export declare function normalizeFameNodeConfig(input?: Partial<FameNodeConfig> | Record<string, unknown> | null): FameNodeConfig;

package/dist/types/naylence/fame/node/node.d.ts

@@ -4,6 +4,7 @@ import type { DeliveryPolicy } from '../delivery/delivery-policy.js';
 import type { SecurityManager } from '../security/security-manager.js';
 import type { CryptoProvider } from '../security/crypto/providers/crypto-provider.js';
 import type { AdmissionClient } from './admission/admission-client.js';
+import type { ConnectionRetryPolicy } from './connection-retry-policy.js';
 import type { NodeEventListener } from './node-event-listener.js';
 import type { StorageProvider, KeyValueStore } from '../storage/index.js';
 import type { EnvelopeFactory } from '@naylence/core';
@@ -39,6 +40,7 @@ export interface FameNodeOptions {
     nodeMetaStore?: KeyValueStore<NodeMetaRecord> | null;
     transportListeners?: TransportListener[];
     cryptoProvider?: CryptoProvider | null;
+    connectionRetryPolicy?: ConnectionRetryPolicy | null;
 }
 type FameNodeOptionsInput = FameNodeOptions & Record<string, unknown>;
 export declare class FameNode extends TaskSpawner implements NodeLike {
@@ -72,6 +74,7 @@ export declare class FameNode extends TaskSpawner implements NodeLike {
     private _handshakeCompleted;
     private _welcomeExpiresAt;
     private _attachExpiresAt;
+    private readonly _connectionRetryPolicy;
     constructor(options?: FameNodeOptionsInput);
     private initializeSessionManager;
     private initializeRootSessionManager;

package/dist/types/naylence/fame/node/upstream-session-manager.d.ts

@@ -1,6 +1,7 @@
 import { TaskSpawner } from '../util/task-spawner.js';
 import { DeliveryOriginType, FameConnector, FameEnvelope, FameEnvelopeHandler, NodeWelcomeFrame } from '@naylence/core';
 import type { AdmissionClient } from './admission/admission-client.js';
+import type { ConnectionRetryPolicy } from './connection-retry-policy.js';
 import type { NodeAttachClient, AttachInfo } from './admission/node-attach-client.js';
 import type { NodeLike } from './node-like.js';
 import type { SessionManager } from './session-manager.js';
@@ -24,6 +25,7 @@ interface UpstreamSessionManagerOptions {
     onAttach: AttachCallback;
     onEpochChange?: EpochCallback;
     admissionClient?: AdmissionClient | null;
+    retryPolicy?: ConnectionRetryPolicy | null;
 }
 type UpstreamSessionManagerOptionsInput = UpstreamSessionManagerOptions & {
     node?: NodeLike;
@@ -68,6 +70,8 @@ export declare class UpstreamSessionManager extends TaskSpawner implements Sessi
     private hadSuccessfulAttach;
     private lastConnectorState;
     private connectEpoch;
+    private initialAttempts;
+    private readonly connectionRetryPolicy;
     private _visibilityHandler;
     constructor(optionsInput: UpstreamSessionManagerOptionsInput);
     get systemId(): string | null;
@@ -82,7 +86,16 @@ export declare class UpstreamSessionManager extends TaskSpawner implements Sessi
     isReady(): boolean;
     awaitReady(timeoutMs?: number): Promise<void>;
     private fsmLoop;
+    /**
+     * Determine whether to fail immediately or continue retrying.
+     * Returns true if we should throw the error instead of retrying.
+     */
+    private shouldFailFastOnError;
     private applyBackoff;
+    /**
+     * 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
+     */
     private sleepWithStop;
     private getNodeAttachGrant;
     private waitEvent;

package/dist/types/naylence/fame/sentinel/sentinel.d.ts

@@ -51,6 +51,7 @@ export declare class Sentinel extends FameNode implements RoutingNodeLike {
     private readonly maxAttachTtlSec;
     private readonly requestedLogicals;
     private readonly attachClient;
+    private readonly connectionRetryPolicy;
     private readonly attachTimeoutMs;
     private readonly cleanupDelayMs;
     private readonly rebindOnAttach;

package/dist/types/version.d.ts

@@ -2,4 +2,4 @@
  * The package version, injected at build time.
  * @internal
  */
-export declare const VERSION = "0.3.15";
+export declare const VERSION = "0.3.16";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naylence/runtime",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "type": "module",
   "description": "Naylence Runtime - Complete TypeScript runtime",
   "author": "Naylence Dev <naylencedev@gmail.com>",