@persistica/flux-mesh 0.0.12 → 0.0.16

package/src/routing/redis/hash/network-agent.redis.sorted-set.d.ts

@@ -8,8 +8,8 @@ export declare class NetworkAgentRedisSortedSet {
     /**
      * Registers a network agent in the sorted set.
      *
-     * @param { TNetworkId_S } networkId
-     * @param { TClientId } socketId
+     * @param { TNetworkId_S } networkId - The network ID
+     * @param { TClientId } socketId - The socket/client ID
      *
      * @returns { Promise<void> }
      */
@@ -17,10 +17,10 @@ export declare class NetworkAgentRedisSortedSet {
     /**
      * Unregisters a network agent from the sorted set.
      *
-     * @param { TNetworkId_S } networkId
-     * @param { TClientId } socketId
+     * @param { TNetworkId_S } networkId - The network ID
+     * @param { TClientId } socketId - The socket/client ID
      *
-     * @returns { Promise<number> }
+     * @returns { Promise<number> } The number of elements removed
      */
     unregisterAgent(networkId: TNetworkId_S, socketId: TClientId): Promise<number>;
 }

package/src/routing/redis/network-agent.redis.d.ts

@@ -2,7 +2,7 @@
  * Register information on a specific network agent.
  */
 import type { RedisClient } from 'bun';
-import type { TAddress, TClientId, TAgentOwnUId, TNetworkId_S } from '@flux/shared/types';
+import type { TClientId, TNetworkId_S } from '@flux/shared/types';
 export declare class NetworkAgentRedis {
     private readonly client;
     private readonly networkAgentRedisSortedSet;
@@ -11,29 +11,53 @@ export declare class NetworkAgentRedis {
     /**
      * Registers a network agent in the sorted set.
      *
-     * @param { TNetworkId_S } networkId
-     * @param { TClientId } socketId
+     * @param { TNetworkId_S } networkId - The network ID
+     * @param { TAddress } address - The client address
+     * @param { TClientId } clientId - The socket ID
+     * @param { TAgentOwnUId } uid - The agent UID
      *
      * @returns { Promise<void> }
+    public async registerNetworkAgent(
+        networkId: TNetworkId_S,
+        address: TAddress,
+        clientId: TClientId,
+        uid: TAgentOwnUId,
+    ): Promise<void> {
+        const key: string = `networks/${networkId}/agents/${clientId}`;
+
+        await this.client.hset(key, {
+            'data-usage': '0',
+            'address': address,
+            'name': uid,
+            'registerAt': new Date().toISOString(),
+        });
+
+        await this.client.expire(key, 500);
+
+        await this.networkAgentRedisSortedSet
+            .registerAgent(
+                networkId,
+                clientId,
+            );
+    }
      */
-    registerNetworkAgent(networkId: TNetworkId_S, clientId: TAddress, socketId: TClientId, uid: TAgentOwnUId): Promise<void>;
     /**
      * Unregisters a network agent from the sorted set.
      *
-     * @param { TNetworkId_S } networkId
-     * @param { TClientId } socketId
+     * @param { TNetworkId_S } networkId - The network ID
+     * @param { TClientId } clientId - The socket ID
      *
-     * @returns { Promise<number> }
+     * @returns { Promise<number> } The number of elements removed
      */
-    unregisterNetworkAgent(networkId: TNetworkId_S, socketId: TClientId): Promise<number>;
+    unregisterNetworkAgent(networkId: TNetworkId_S, clientId: TClientId): Promise<number>;
     /**
+     * Caches the data usage for a network agent to be pushed periodically.
      *
-     * @param socketId
-     * @param usage
-     *
-     * @returns { void }
+     * @param { TNetworkId_S } networkId - The network ID
+     * @param { TClientId } clientId - The socket ID
+     * @param { number } usage - The data usage in bytes
      */
-    registerDataUsage(networkId: TNetworkId_S, socketId: TClientId, usage: number): void;
+    registerDataUsage(networkId: TNetworkId_S, clientId: TClientId, usage: number): void;
     /**
      * Pushes the data usage to the Redis server.
      *

package/src/routing/redis/redis-connection.class.d.ts

@@ -1,11 +1,13 @@
-import type { TAddress, TClientId, TProcessAddress } from '@flux/shared/types';
+import type { TAddress, TClientId, TNetworkId_S, TNetworkToken_S, TProcessAddress } from '@flux/shared/types';
 import { NetworkAuthorityRedisSortedSet } from '@flux/mesh/store/redis/network-authority';
 import { NetworkAgentRedisService } from '@flux/mesh/store/redis/network-agent';
 import type { TGlobalChannel } from '../global-channel/global-channel-pubsub.class';
 /**
- * Singleton function to get the Redis connection
+ * Singleton function to get the Redis connection.
  *
- * @returns
+ * @param { string } [connectionString] - Optional connection string override
+ *
+ * @returns { RedisConnection } The singleton Redis connection
  */
 export declare const getMeshRedisConnection: (connectionString?: string) => RedisConnection;
 export type MessageCallback = (message: string, channel?: string) => unknown;
@@ -16,14 +18,20 @@ export declare class RedisConnection {
     readonly networkAuthoritySet: NetworkAuthorityRedisSortedSet;
     readonly networkAgentRedisService: NetworkAgentRedisService;
     readonly hash: {
-        sadd: (key: Bun.RedisClient.KeyLike, member: string) => Promise<number>;
-        hmset: (key: Bun.RedisClient.KeyLike, fieldValues: string[]) => Promise<string>;
+        sadd: (key: Bun.RedisClient.KeyLike, ...members: string[]) => Promise<number>;
+        hset: {
+            (key: Bun.RedisClient.KeyLike, fields: Record<string | number, Bun.RedisClient.KeyLike | number>): Promise<number>;
+            (key: Bun.RedisClient.KeyLike, field: Bun.RedisClient.KeyLike, value: Bun.RedisClient.KeyLike, ...rest: Bun.RedisClient.KeyLike[]): Promise<number>;
+        };
         smembers: (key: Bun.RedisClient.KeyLike) => Promise<string[]>;
-        srem: (key: Bun.RedisClient.KeyLike, member: string) => Promise<number>;
+        srem: (key: Bun.RedisClient.KeyLike, ...members: string[]) => Promise<number>;
         scard: (key: Bun.RedisClient.KeyLike) => Promise<number>;
         del: (...keys: Bun.RedisClient.KeyLike[]) => Promise<number>;
         hincrby: (key: Bun.RedisClient.KeyLike, field: string, increment: string | number) => Promise<number>;
-        hmget: (key: Bun.RedisClient.KeyLike, fields: string[]) => Promise<Array<string | null>>;
+        hmget: {
+            (key: Bun.RedisClient.KeyLike, ...fields: string[]): Promise<Array<string | null>>;
+            (key: Bun.RedisClient.KeyLike, fields: string[]): Promise<Array<string | null>>;
+        };
         expire: (key: Bun.RedisClient.KeyLike, seconds: number) => Promise<number>;
     };
     constructor(_optionsOrURL: string | {
@@ -31,35 +39,76 @@ export declare class RedisConnection {
         url: string;
     });
     /**
-     *
-     * @param { TProcessAddress }   skipProcessAddress
-     * @param { TGlobalChannel  }   channel
-     * @param { string }            message
-     *
-     * @returns { Promise<void> }
+     * Publishes a websocket channel event to all processes, except the one specified.
      */
     publishWebsocketChannelEvent(skipProcessAddress: TProcessAddress, channel: TGlobalChannel, message: string): Promise<void>;
     /**
-     *
-     * @returns { void }
+     * Subscribes to websocket channel events from all processes.
      */
     subscribeWebsocketChannelEvent(callback: (channel: TGlobalChannel, skipProcessAddress: TProcessAddress, message: string) => unknown): Promise<void>;
     /**
+     * Publishes the current set of valid token values for a network.
+     * Called by the portal whenever tokens are created, rotated, or deleted.
+     */
+    publishNetworkTokenEvent(networkId: TNetworkId_S, tokens: TNetworkToken_S[]): Promise<void>;
+    /**
+     * Subscribes to network token update events.
+     * The mesh calls this to keep its local token cache in sync.
+     */
+    subscribeToNetworkTokenEvents(callback: (networkId: TNetworkId_S, tokens: TNetworkToken_S[]) => void): void;
+    /**
+     * Persists the current set of valid token values for a network into a
+     * Redis Set so that mesh processes can bootstrap their local caches after
+     * a cold start (i.e. before any pub/sub event has been received).
      *
-     * @param { TAddress | TProcessAddress }    address
-     * @param { string }                        message
+     * The key format is: `:flux:network-tokens/{networkId}/values`.
      *
-     * @returns { Promise<void> }
+     * Called by the portal on every token mutation alongside
+     * {@link publishNetworkTokenEvent}.
+     */
+    setNetworkTokenValues(networkId: TNetworkId_S, tokens: TNetworkToken_S[]): Promise<void>;
+    /**
+     * Reads the set of valid token values for a network from the persistent
+     * Redis Set written by the portal.
+     *
+     * Used by {@link NetworkTokenCache} for cold-start bootstrapping.
+     */
+    getNetworkTokenValues(networkId: TNetworkId_S): Promise<TNetworkToken_S[]>;
+    publishCustom(subChannel: 'kick-client', destinationProcessAddress: TProcessAddress, message: string): Promise<void>;
+    subscribeToCustom(subChannel: 'kick-client', destinationProcessAddress: TProcessAddress, callback: (data: string) => void): void;
+    /**
+     * Publishes a message directly to an address.
      */
     directPublish(address: TAddress | TProcessAddress, message: string): Promise<void>;
+    /**
+     * Subscribes to messages on a Redis channel.
+     */
     subscribe(channelId: TProcessAddress | TClientId, callback: MessageCallback): void;
+    /**
+     * Unsubscribes from messages on a Redis channel.
+     */
     unsubscribe(channelId: string, callback: MessageCallback): void;
+    /**
+     * Subscribes to data packets published on a specific network channel.
+     * Invokes the callback with the raw data string from each packet.
+     */
+    subscribeToNetworkChannel(networkId: string, channelName: string, callback: (clientId: TClientId, data: string) => void): void;
+    /**
+     * Unsubscribes a callback from data packets on a specific network channel.
+     */
+    unsubscribeFromNetworkChannel(networkId: string, channelName: string, callback: (clientId: TClientId, data: string) => void): void;
+    /**
+     * Marks the given address as connected in Redis.
+     */
     setConnected(address: string): Promise<void>;
+    /**
+     * Marks the given address as disconnected in Redis.
+     */
     setDisconnected(_address: string): Promise<void>;
     /**
      * Disconnects the Redis cache and pub/sub.
      *
-     * @returns { void }
+     * @returns { Promise<void> }
      */
-    disconnect(): void;
+    disconnect(): Promise<void>;
 }

package/src/routing/rpc/core/global-rpc-client.class.d.ts

@@ -14,18 +14,17 @@ export declare class GlobalRPCClient<TMethods> {
     /**
      * Calls a function on the other side.
      *
-     * @param { TAddress } rpcServerClientAddress
-     * @param { TMethods } method
+     * @param { TAddress } rpcServerClientAddress - The address of the RPC server client
+     * @param { TMethods } method - The method name to call
+     * @param { any[] } params - The parameters to pass
      *
-     * @returns { Promise<any> }
+     * @returns { Promise<any> } The result from the remote method
      */
     call(rpcServerClientAddress: TAddress, method: TMethods, ...params: any): Promise<any>;
     /**
      * Handles the response from the server.
      *
-     * @param { RPCResponse }   response
-     *
-     * @returns { boolean }
+     * @param { RPCResponse } response - The response from the RPC server
      */
     private handleResponseMessage;
 }
@@ -40,18 +39,16 @@ export declare class GlobalRPCClient2<TMethods> {
     /**
      * Calls a function on the other side.
      *
-     * @param { TAddress } rpcServerClientAddress
-     * @param { TMethods } method
+     * @param { TMethods } method - The method name to call
+     * @param { any[] } params - The parameters to pass
      *
-     * @returns { Promise<any> }
+     * @returns { Promise<any> } The result from the remote method
      */
     call(method: TMethods, ...params: any): Promise<any>;
     /**
      * Handles the response from the server.
      *
-     * @param { RPCResponse }   response
-     *
-     * @returns { boolean }
+     * @param { RPCResponse } response - The response from the RPC server
      */
     private handleResponseMessage;
 }

package/src/register/register-network-authority.class.d.ts

@@ -1,34 +0,0 @@
-import { type TAddress, type TClientId, type TNetworkId_S } from '@flux/shared/types';
-import type { TFluxClientUID } from '@flux/shared/utils';
-export declare class NetworkAuthorityManager {
-    private readonly redisConnection;
-    private readonly cache;
-    register(networkId: TNetworkId_S, socketId: TClientId, machineUID?: TFluxClientUID): Promise<void>;
-    unregister(networkId: TNetworkId_S, networkAuthorityAddress: TAddress): void;
-    /**
-     * Used for cleanup, in case of discovering an idle authority.
-     *
-     * @param { TNetworkId_S }  networkId
-     * @param { TAddress }      networkAuthorityAddress
-     *
-     * @returns { void }
-     */
-    unregisterGlobal(networkId: TNetworkId_S, networkAuthorityAddress: TAddress): void;
-    /**
-     * Resolves a random network authority address for a given network ID.
-     *
-     * @param { TNetworkId_S }  networkId
-     *
-     * @returns { Promise<TAddress> }
-     */
-    resolveNetworkAuthorityAddressOrThrow(networkId: TNetworkId_S): Promise<TAddress>;
-    /**
-     * Removes a client.
-     *
-     * @param { TNetworkId_S }  networkId
-     * @param { TAddress }      networkAuthorityAddress
-     *
-     * @returns { void }
-     */
-    removeUnresponsiveClient(networkId: TNetworkId_S, networkAuthorityAddress: TAddress): void;
-}