@persistica/flux-mesh 0.0.7 → 0.0.8

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@persistica/flux-mesh",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Persistica Flux Mesh",
   "type": "module",
   "keywords": [],
   "publishConfig": {
     "access": "public"
   },
-  "main": "./index.cjs",
-  "types": "./index.d.ts",
+  "exports": "./index.js",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rujorgensen/persistica.git"
@@ -18,8 +19,5 @@
   "bugs": {
     "url": "https://github.com/rujorgensen/persistica/issues"
   },
-  "homepage": "https://github.com/rujorgensen/persistica#readme",
-  "dependencies": {
-    "alpinejs": "^3.14.9"
-  }
+  "homepage": "https://github.com/rujorgensen/persistica#readme"
 }

package/src/_classes/web-rtc-client-interface.class.d.ts

@@ -0,0 +1,20 @@
+import type { TProcessAddress } from '@flux/shared/types';
+import { GlobalRPCClient2 } from '../routing/rpc/core/global-rpc-client.class';
+import { type TRPCResponseCallbackFunction, RPCClient } from '@flux/shared/ws';
+export declare class WebRTCClient extends RPCClient<'createOffer' | 'acceptOffer' | 'acceptAnswer' | 'answerAcceptedByInitiator'> {
+    private readonly _originProcessAddress;
+    private readonly _sendToRPCServer;
+    private readonly _handleResponseMessage;
+    constructor(_originProcessAddress: TProcessAddress, _sendToRPCServer: (data: any, // ! Use 'unknown' or Bun.BufferSource (does not work)
+    compress?: boolean | undefined) => number, _handleResponseMessage: (fn: TRPCResponseCallbackFunction) => void);
+    createOffer(): Promise<unknown>;
+    acceptOfferAndCreateAnswer(offer: unknown): Promise<unknown>;
+    acceptAnswer(answer: unknown): Promise<boolean>;
+    answerWasAccepted(answerAccepted: boolean): Promise<boolean>;
+}
+export declare class GlobalWebRTCClient extends GlobalRPCClient2<'createOffer' | 'acceptOffer' | 'acceptAnswer' | 'answerAcceptedByInitiator'> {
+    createOffer(): Promise<unknown>;
+    acceptOfferAndCreateAnswer(offer: unknown): Promise<unknown>;
+    acceptAnswer(answer: unknown): Promise<boolean>;
+    answerWasAccepted(answerAccepted: boolean): Promise<boolean>;
+}

package/src/_routes/auth/network-authority.post.route.d.ts

@@ -0,0 +1,7 @@
+import type * as Bun from 'bun';
+/**
+ * This route is used to authorize a network authority.
+ *
+ * @returns { Promise<Response> }
+ */
+export declare const authorizeNetworkAuthority: (request: Bun.BunRequest) => Promise<Response>;

package/src/_routes/auth/network-client.post.route.d.ts

@@ -0,0 +1,12 @@
+import type { BunRequest } from 'bun';
+import type { GlobalRPCClient } from '../../routing/rpc/core/global-rpc-client.class';
+import type { NetworkAuthorityManager } from '../../register/register-network-authority.class';
+/**
+ *
+ * @param { BunRequest }                    request
+ * @param { NetworkAuthorityManager }       networkAuthorityManager
+ * @param { GlobalRPCClient<'authorize'> }  globalRPCClient
+ *
+ * @returns { void }
+ */
+export declare const authorizeNetworkAgent: (request: BunRequest, networkAuthorityManager: NetworkAuthorityManager, globalRPCClient: GlobalRPCClient<"authorize">) => Promise<Response>;

package/src/_routes/options.route.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Standard CORS response.
+ *
+ * @returns { Response }
+ */
+export declare const OPTIONS_RESPONSE: () => Response;

package/src/auth/auth.d.ts

@@ -0,0 +1,22 @@
+import type { TNetworkId_S } from '@flux/shared/types';
+import type { TFluxClientUID } from '@flux/shared/utils';
+export type TTokenPayload = {
+    networkId: TNetworkId_S;
+    claim?: string;
+    isAuthority?: boolean;
+    machineUID?: TFluxClientUID;
+    agentUID?: string;
+};
+export type TTokenPayloadJWT = string & {
+    __brand: 'TokenPayloadJWT';
+};
+/**
+ * Generates JWT string from a token payload.
+ *
+ * @param { TTokenPayload }     payload
+ * @param { number }            expiresIn
+ *
+ * @returns { TTokenPayloadJWT }
+ */
+export declare const generateToken: (payload: TTokenPayload, expiresIn?: number) => string;
+export declare const verifyTokenOrThrow: (token: unknown) => TTokenPayload;

package/src/business-logic/channels/channel-manager.class.d.ts

@@ -0,0 +1,69 @@
+import { type TAddress, type TChannelName, type TNetworkId_S } from '@flux/shared/types';
+import type { GlobalChannelPubsub } from '../../routing/global-channel/global-channel-pubsub.class';
+export declare class NetworkChannelManager {
+    private readonly _globalChannelPubsub;
+    private readonly channelUsageCount;
+    private readonly redisConnection;
+    private readonly networkChannelHash;
+    constructor(_globalChannelPubsub: GlobalChannelPubsub);
+    /**
+     * Checks if a channel can have more members.
+     *
+     * ! TODO Don't query the database repeatedly, implement local synced cache.
+     *
+     * @param { TNetworkId_S } networkId
+     * @param { TChannelName } channelName
+     *
+     * @returns { Promise<boolean> }
+     */
+    canHaveMembers(networkId: TNetworkId_S, channelName: TChannelName): Promise<boolean>;
+    /**
+     * Joins a network channel.
+     *
+     * @param { TNetworkId_S }  networkId
+     * @param { TChannelName }  channelName
+     * @param { TAddress }      clientAddress
+     *
+     * @returns { void }
+     */
+    joinNetworkChannel(networkId: TNetworkId_S, channelName: TChannelName, clientAddress: TAddress): void;
+    /**
+     * Leaves a network channel.
+     *
+     * @param { TNetworkId_S }  networkId
+     * @param { TChannelName }  channelName
+     * @param { TAddress }      clientAddress
+     *
+     * @returns { Promise<void> }
+     */
+    leaveNetworkChannel(networkId: TNetworkId_S, channelName: TChannelName, clientAddress: TAddress): Promise<void>;
+    /**
+     * Leaves all network channels.
+     *
+     * @param { TNetworkId_S }          networkId
+     * @param { TAddress }              clientAddress
+     * @param { Set<TChannelName> }     channelNames
+     *
+     * @returns { void }
+     */
+    leaveAllNetworkChannels(networkId: TNetworkId_S, clientAddress: TAddress, channelNames: Set<TChannelName>): void;
+    /**
+     * Creates a network channel if it does not exist.
+     *
+     * @param { TNetworkId_S }  networkId
+     * @param { TChannelName }  channelName
+     *
+     * @returns { void }
+     */
+    private createNetworkChannelIfNotExist;
+    /**
+     * Increases the usage count of a channel.
+     *
+     * @param { TNetworkId_S } networkId
+     * @param { TChannelName } channelName
+     * @param { number } usage
+     *
+     * @returns { void }
+     */
+    increaseUsageCount(networkId: TNetworkId_S, channelName: TChannelName, usage: number): void;
+}

package/src/connected-client-socket.types.d.ts

@@ -0,0 +1,21 @@
+import type { TAddress, TAgentOwnUId, TChannelName, TClientId, TNetworkId_S } from '@flux/shared/types';
+import type { TFluxClientUID } from '@flux/shared/utils';
+import type { WebRTCClient } from './_classes/web-rtc-client-interface.class';
+import type { RPCClient } from '@flux/shared/ws';
+export type TConnectedClientSocket = Bun.ServerWebSocket<{
+    ip: Bun.SocketAddress | null;
+    id: TClientId;
+    uid?: TAgentOwnUId;
+    address: TAddress;
+    networkId: TNetworkId_S;
+    isAuthority?: boolean;
+    rtcClient?: WebRTCClient;
+    claim?: string;
+    rpcClient: RPCClient<'channel'>;
+    channelNames: Set<TChannelName>;
+    machineUID?: TFluxClientUID;
+    throughput: {
+        bytes: number;
+        packets: number;
+    };
+}>;

package/src/index.d.ts

@@ -0,0 +1 @@
+export { FluxMeshServer, } from './main';

package/src/main.d.ts

@@ -0,0 +1,25 @@
+declare global {
+    var meshLoadCount: number | null;
+}
+type TOptions = {
+    port?: number;
+    redisConnectionString?: string;
+};
+export declare class FluxMeshServer {
+    private readonly optionsOrPort?;
+    private readonly redisConnection;
+    private readonly onReadyListeners;
+    private readonly bunServer;
+    private readonly globalChannelPubsub;
+    private readonly channelManager;
+    private readonly options;
+    constructor(optionsOrPort?: (TOptions | number) | undefined);
+    onReady(fn: () => void): void;
+    /**
+     * Gracefully shuts down the server.
+     *
+     * @returns { Promise<void> }
+     */
+    stop(): Promise<void>;
+}
+export {};

package/src/orchestrators/facilitate-webrtc-connection.class.d.ts

@@ -0,0 +1,2 @@
+import { GlobalWebRTCClient, WebRTCClient } from '../_classes/web-rtc-client-interface.class';
+export declare const facilitateWebRTCConnection: (initiator: WebRTCClient | GlobalWebRTCClient, remoteClient: GlobalWebRTCClient) => Promise<void>;

package/src/register/network-client-manager.class.d.ts

@@ -0,0 +1,38 @@
+import type { NetworkAgentRedisService } from '@flux/mesh/store/redis/network-agent';
+import { NetworkUsageRedisCacheService } from '@flux/mesh/store/redis/network-usage';
+import type { TAddress, TClientId, TAgentOwnUId, TNetworkId_S } from '@flux/shared/types';
+import type { TFluxClientUID } from '@flux/shared/utils';
+export declare class NetworkAgentManager {
+    readonly networkAgentRedisService: NetworkAgentRedisService;
+    readonly networkUsageRedisCacheService: NetworkUsageRedisCacheService;
+    private readonly redisConnection;
+    private readonly cache;
+    private readonly timers;
+    constructor();
+    /**
+     * Register an agent.
+     *
+     * @param { TNetworkId_S }              networkId
+     * @param { TClientId }                 id
+     * @param { Bun.SocketAddress | null }  ip
+     * @param { TAddress }                  address
+     * @param { TAgentOwnUId }              [uid]
+     *
+     * @returns { void }
+     */
+    registerAgent(networkId: TNetworkId_S, id: TClientId, ip: Bun.SocketAddress | null, address: TAddress, throughput: {
+        bytes: number;
+        packets: number;
+    }, uid?: TAgentOwnUId, machineUID?: TFluxClientUID): Promise<void>;
+    /**
+     * Unregisters a network agent UID and associated data from the Redis hash.
+     *
+     * @param { TNetworkId_S }      networkId
+     * @param { TClientId }         clientId
+     * @param { TAgentOwnUId }     clientOwnUId
+     *
+     * @returns { void }
+     */
+    unregisterNetworkAgent(networkId: TNetworkId_S, clientId: TClientId, clientOwnUId?: TAgentOwnUId): void;
+    resolveNetworkClientAddressByUid(networkId: TNetworkId_S, clientOwnUId: TAgentOwnUId): Promise<TAddress>;
+}

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

@@ -0,0 +1,34 @@
+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;
+}

package/src/routing/addressing.utils.d.ts

@@ -0,0 +1,9 @@
+import type { TMachineAddress, TProcessId, TProcessAddress } from '@flux/shared/types';
+export declare const readProcessId: () => TProcessId;
+export declare const readMachineAddress: () => TMachineAddress;
+/**
+ * Returns the process address.
+ *
+ * @returns { TProcessAddress }
+ */
+export declare const readProcessAddress: () => TProcessAddress;

package/src/routing/global-channel/global-channel-pubsub.class.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 1. Detects global events and publishes them to all clients subscribed to the websocket channel system.
+ *
+ * 2.   Sends messages to all nodes in the cluster, and when reached, publishes locally
+ *      on the server channel to everyone subscribed.
+ */
+import type { TProcessAddress } from '@flux/shared/types';
+import type { TConnectedClientSocket } from '../../connected-client-socket.types';
+import type { RedisConnection } from '../redis/redis-connection.class';
+export type TGlobalChannel = string & {
+    __brand: 'global-channel';
+};
+export declare class GlobalChannelPubsub {
+    private readonly redisConnection;
+    private readonly bunServer;
+    private readonly processAddress;
+    constructor(redisConnection: RedisConnection, bunServer: Bun.Server, processAddress: TProcessAddress);
+    /**
+     * Subscribes to the websocket channel event and publishes it on the local process.
+     *
+     * @returns { void }
+     */
+    private subscribeWebsocketChannelEvent;
+    /**
+     * Publishes a message to the given channel.
+     *
+     * @param { string }  channel
+     * @param { string }  message
+     * @param { TConnectedClientSocket }  [ws]
+     *
+     * @returns { Promise<void> }
+     */
+    publish(channel: string, message: string, ws?: TConnectedClientSocket): Promise<void>;
+}

package/src/routing/incomming-message-router.class.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Route messages to the correct destination.
+ */
+import type { TClientId } from '@flux/shared/types';
+export declare class IncommingMessageRouter {
+    private readonly onLocal;
+    private readonly redisConnection;
+    constructor(onLocal: (clientId: TClientId, onMessage: (message: string) => void) => void);
+}

package/src/routing/outgoing-message-router.class.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Route messages to the correct destination.
+ */
+import { type TAddress, type TClientId } from '@flux/shared/types';
+export declare class OutgoingMessageRouter {
+    private readonly passToLocalClientOrThrowUnknownClient;
+    private readonly processId;
+    private readonly machineAddress;
+    private readonly redisConnection;
+    constructor(passToLocalClientOrThrowUnknownClient: (clientId: TClientId, message: string) => void);
+    /**
+     *
+     * @param address
+     * @param message
+     *
+     * @returns
+     */
+    message(address: TAddress, message: string): void;
+}

package/src/routing/process-message-router.class.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Route messages to the correct process if necessary.
+ */
+import { type TCallbackFunction, type TProcessAddress } from '@flux/shared/types';
+export declare class ProcessMessageRouter {
+    private readonly machineAddress;
+    private readonly processAddress;
+    private readonly processId;
+    private readonly redisConnection;
+    private readonly localCallbacks;
+    /**
+     * Sends a message to a process.
+     *
+     * @param { TProcessAddress }   address
+     * @param { string }            message
+     *
+     * @returns
+     */
+    message(address: TProcessAddress, message: string): void;
+    /**
+     * Subscribe to mesaages for local process.
+     *
+     * @param message
+     *
+     * @returns { void }
+     */
+    subscribe(onMessage: TCallbackFunction): void;
+}

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

@@ -0,0 +1,26 @@
+import type { RedisClient } from 'bun';
+import type { TClientId, TNetworkId_S } from '@flux/shared/types';
+export declare class NetworkAgentRedisSortedSet {
+    private readonly client;
+    private readonly processId;
+    private readonly machineAddress;
+    constructor(client: RedisClient);
+    /**
+     * Registers a network agent in the sorted set.
+     *
+     * @param { TNetworkId_S } networkId
+     * @param { TClientId } socketId
+     *
+     * @returns { Promise<void> }
+     */
+    registerAgent(networkId: TNetworkId_S, socketId: TClientId): Promise<void>;
+    /**
+     * Unregisters a network agent from the sorted set.
+     *
+     * @param { TNetworkId_S } networkId
+     * @param { TClientId } socketId
+     *
+     * @returns { Promise<number> }
+     */
+    unregisterAgent(networkId: TNetworkId_S, socketId: TClientId): Promise<number>;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Register information on a specific network agent.
+ */
+import type { RedisClient } from 'bun';
+import type { TAddress, TClientId, TAgentOwnUId, TNetworkId_S } from '@flux/shared/types';
+export declare class NetworkAgentRedis {
+    private readonly client;
+    private readonly networkAgentRedisSortedSet;
+    private readonly cashedDataUsage;
+    constructor(client: RedisClient);
+    /**
+     * Registers a network agent in the sorted set.
+     *
+     * @param { TNetworkId_S } networkId
+     * @param { TClientId } socketId
+     *
+     * @returns { Promise<void> }
+     */
+    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
+     *
+     * @returns { Promise<number> }
+     */
+    unregisterNetworkAgent(networkId: TNetworkId_S, socketId: TClientId): Promise<number>;
+    /**
+     *
+     * @param socketId
+     * @param usage
+     *
+     * @returns { void }
+     */
+    registerDataUsage(networkId: TNetworkId_S, socketId: TClientId, usage: number): void;
+    /**
+     * Pushes the data usage to the Redis server.
+     *
+     * @returns { Promise<void> }
+     */
+    private pushDataUsage;
+}

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

@@ -0,0 +1,65 @@
+import type { TAddress, TClientId, 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
+ *
+ * @returns
+ */
+export declare const getMeshRedisConnection: (connectionString?: string) => RedisConnection;
+export type MessageCallback = (message: string, channel?: string) => unknown;
+export declare class RedisConnection {
+    private readonly _optionsOrURL;
+    private readonly cacheClient;
+    private readonly pubSub;
+    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>;
+        smembers: (key: Bun.RedisClient.KeyLike) => Promise<string[]>;
+        srem: (key: Bun.RedisClient.KeyLike, member: 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>>;
+        expire: (key: Bun.RedisClient.KeyLike, seconds: number) => Promise<number>;
+    };
+    constructor(_optionsOrURL: string | {
+        name?: string;
+        url: string;
+    });
+    /**
+     *
+     * @param { TProcessAddress }   skipProcessAddress
+     * @param { TGlobalChannel  }   channel
+     * @param { string }            message
+     *
+     * @returns { Promise<void> }
+     */
+    publishWebsocketChannelEvent(skipProcessAddress: TProcessAddress, channel: TGlobalChannel, message: string): Promise<void>;
+    /**
+     *
+     * @returns { void }
+     */
+    subscribeWebsocketChannelEvent(callback: (channel: TGlobalChannel, skipProcessAddress: TProcessAddress, message: string) => unknown): Promise<void>;
+    /**
+     *
+     * @param { TAddress | TProcessAddress }    address
+     * @param { string }                        message
+     *
+     * @returns { Promise<void> }
+     */
+    directPublish(address: TAddress | TProcessAddress, message: string): Promise<void>;
+    subscribe(channelId: TProcessAddress | TClientId, callback: MessageCallback): void;
+    unsubscribe(channelId: string, callback: MessageCallback): void;
+    setConnected(address: string): Promise<void>;
+    setDisconnected(_address: string): Promise<void>;
+    /**
+     * Disconnects the Redis cache and pub/sub.
+     *
+     * @returns { void }
+     */
+    disconnect(): void;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The class to handling the *calling* side of the RPC.
+ */
+import { type TAddress } from '@flux/shared/types';
+import type { OutgoingMessageRouter } from '../../outgoing-message-router.class';
+import type { ProcessMessageRouter } from '../../process-message-router.class';
+export declare class GlobalRPCClient<TMethods> {
+    private readonly _outgoingMessageRouter;
+    private readonly _processMessageRouter;
+    private requestId;
+    private readonly pendingRequests;
+    private readonly processAddress;
+    constructor(_outgoingMessageRouter: OutgoingMessageRouter, _processMessageRouter: ProcessMessageRouter);
+    /**
+     * Calls a function on the other side.
+     *
+     * @param { TAddress } rpcServerClientAddress
+     * @param { TMethods } method
+     *
+     * @returns { Promise<any> }
+     */
+    call(rpcServerClientAddress: TAddress, method: TMethods, ...params: any): Promise<any>;
+    /**
+     * Handles the response from the server.
+     *
+     * @param { RPCResponse }   response
+     *
+     * @returns { boolean }
+     */
+    private handleResponseMessage;
+}
+export declare class GlobalRPCClient2<TMethods> {
+    private readonly _rpcServerClientAddress;
+    private readonly _outgoingMessageRouter;
+    private readonly _processMessageRouter;
+    private requestId;
+    private readonly pendingRequests;
+    private readonly processAddress;
+    constructor(_rpcServerClientAddress: TAddress, _outgoingMessageRouter: OutgoingMessageRouter, _processMessageRouter: ProcessMessageRouter);
+    /**
+     * Calls a function on the other side.
+     *
+     * @param { TAddress } rpcServerClientAddress
+     * @param { TMethods } method
+     *
+     * @returns { Promise<any> }
+     */
+    call(method: TMethods, ...params: any): Promise<any>;
+    /**
+     * Handles the response from the server.
+     *
+     * @param { RPCResponse }   response
+     *
+     * @returns { boolean }
+     */
+    private handleResponseMessage;
+}

package/src/test.spec.d.ts

@@ -0,0 +1 @@
+export {};