@floegence/floe-webapp-protocol 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import { type JSX } from 'solid-js';
+import type { ChannelInitGrant, Client, ClientObserverLike, DirectConnectInfo } from '@floegence/flowersec-core';
+import { type ControlplaneConfig } from './controlplane';
+/**
+ * Connection status
+ */
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+interface ProtocolContextValue {
+    status: () => ConnectionStatus;
+    error: () => Error | null;
+    client: () => Client | null;
+    connect: (config: ConnectConfig) => Promise<void>;
+    disconnect: () => void;
+}
+/**
+ * Configuration for connecting to a flowersec server
+ */
+export interface AutoReconnectConfig {
+    /**
+     * Enable auto reconnect on failure / unexpected disconnect.
+     * Default: false.
+     */
+    enabled?: boolean;
+    /** Maximum total attempts (including the first). Default: 5. */
+    maxAttempts?: number;
+    /** Base delay for the first retry. Default: 500ms. */
+    initialDelayMs?: number;
+    /** Max delay cap. Default: 10s. */
+    maxDelayMs?: number;
+    /** Exponential backoff factor. Default: 1.8. */
+    factor?: number;
+    /** Random jitter ratio in [-ratio, +ratio]. Default: 0.2. */
+    jitterRatio?: number;
+}
+export interface ConnectConfig {
+    mode?: 'tunnel' | 'direct';
+    observer?: ClientObserverLike;
+    keepaliveIntervalMs?: number;
+    connectTimeoutMs?: number;
+    handshakeTimeoutMs?: number;
+    autoReconnect?: AutoReconnectConfig;
+    controlplane?: ControlplaneConfig;
+    grant?: ChannelInitGrant;
+    directInfo?: DirectConnectInfo;
+}
+export declare function ProtocolProvider(props: {
+    children: JSX.Element;
+}): JSX.Element;
+export declare function useProtocol(): ProtocolContextValue;
+export {};

package/dist/controlplane.d.ts

@@ -0,0 +1,13 @@
+import { type ChannelInitGrant } from '@floegence/flowersec-core';
+export interface ControlplaneConfig {
+    baseUrl: string;
+    endpointId: string;
+}
+/**
+ * 向控制面请求隧道连接凭证（grant）。
+ *
+ * 说明：
+ * - `.design.md` 约定的接口为 POST `${baseUrl}/v1/channel/init`，body: { endpoint_id }
+ * - 返回体结构按设计约定：`{ grant_client: ChannelInitGrant }`
+ */
+export declare function requestChannelGrant(config: ControlplaneConfig): Promise<ChannelInitGrant>;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ProtocolProvider, useProtocol, type ConnectionStatus, type ConnectConfig, type AutoReconnectConfig } from './client';
+export { useRpc, RpcError, ProtocolNotConnectedError } from './rpc';
+export { requestChannelGrant, type ControlplaneConfig } from './controlplane';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,14 @@
+import { ProtocolProvider as e, useProtocol as t } from "./index2.js";
+import { ProtocolNotConnectedError as c, RpcError as s, useRpc as d } from "./index3.js";
+import { requestChannelGrant as f } from "./index4.js";
+import { ReservedTypeIds as m, TypeIds as x } from "./index5.js";
+export {
+  c as ProtocolNotConnectedError,
+  e as ProtocolProvider,
+  m as ReservedTypeIds,
+  s as RpcError,
+  x as TypeIds,
+  f as requestChannelGrant,
+  t as useProtocol,
+  d as useRpc
+};

package/dist/index2.js

@@ -0,0 +1,189 @@
+import { createContext as T, onCleanup as E, createComponent as P, useContext as k } from "solid-js";
+import { createStore as A } from "solid-js/store";
+import { requestChannelGrant as W } from "./index4.js";
+const R = T();
+function y(a) {
+  return a != null && a.enabled ? {
+    enabled: !0,
+    maxAttempts: Math.max(1, a.maxAttempts ?? 5),
+    initialDelayMs: Math.max(0, a.initialDelayMs ?? 500),
+    maxDelayMs: Math.max(0, a.maxDelayMs ?? 1e4),
+    factor: Math.max(1, a.factor ?? 1.8),
+    jitterRatio: Math.max(0, a.jitterRatio ?? 0.2)
+  } : {
+    enabled: !1,
+    maxAttempts: 1,
+    initialDelayMs: 500,
+    maxDelayMs: 1e4,
+    factor: 1.8,
+    jitterRatio: 0.2
+  };
+}
+function j(a, c) {
+  const i = Math.min(c.maxDelayMs, c.initialDelayMs * Math.pow(c.factor, a)), l = c.jitterRatio <= 0 ? 0 : i * c.jitterRatio * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(i + l));
+}
+function H(a) {
+  const [c, i] = A({
+    status: "disconnected",
+    error: null,
+    client: null
+  });
+  let l = 0, u = null, d = null, m = null;
+  const h = () => {
+    d && (clearTimeout(d), d = null), m == null || m(), m = null;
+  }, b = (r) => new Promise((e) => {
+    m = e, d = setTimeout(() => {
+      d = null, m = null, e();
+    }, r);
+  }), M = () => {
+    h(), u = null, l += 1, c.client && c.client.close(), i({
+      status: "disconnected",
+      error: null,
+      client: null
+    });
+  }, w = (r, e, t) => {
+    if (r !== l || u !== e || c.status !== "connected") return;
+    if (!y(e.autoReconnect).enabled) {
+      i({
+        status: "error",
+        error: t,
+        client: null
+      });
+      return;
+    }
+    h(), l += 1;
+    const n = l;
+    i({
+      status: "connecting",
+      error: t,
+      client: null
+    }), x(n, e).catch(() => {
+    });
+  }, C = (r, e) => {
+    const t = e.observer;
+    return {
+      onConnect: (...o) => {
+        var n;
+        return (n = t == null ? void 0 : t.onConnect) == null ? void 0 : n.call(t, ...o);
+      },
+      onAttach: (...o) => {
+        var n;
+        return (n = t == null ? void 0 : t.onAttach) == null ? void 0 : n.call(t, ...o);
+      },
+      onHandshake: (...o) => {
+        var n;
+        return (n = t == null ? void 0 : t.onHandshake) == null ? void 0 : n.call(t, ...o);
+      },
+      onWsClose: (o, n) => {
+        var s;
+        (s = t == null ? void 0 : t.onWsClose) == null || s.call(t, o, n), o === "peer_or_error" && w(r, e, new Error(`WebSocket closed (${n ?? "unknown"})`));
+      },
+      onWsError: (o) => {
+        var n;
+        (n = t == null ? void 0 : t.onWsError) == null || n.call(t, o), w(r, e, new Error(`WebSocket error: ${o}`));
+      },
+      onRpcCall: (...o) => {
+        var n;
+        return (n = t == null ? void 0 : t.onRpcCall) == null ? void 0 : n.call(t, ...o);
+      },
+      onRpcNotify: (...o) => {
+        var n;
+        return (n = t == null ? void 0 : t.onRpcNotify) == null ? void 0 : n.call(t, ...o);
+      }
+    };
+  }, f = async (r, e) => {
+    const {
+      connectTunnelBrowser: t,
+      connectDirectBrowser: o
+    } = await import("@floegence/flowersec-core/browser"), n = {
+      observer: C(r, e),
+      keepaliveIntervalMs: e.keepaliveIntervalMs ?? 15e3,
+      connectTimeoutMs: e.connectTimeoutMs ?? 1e4,
+      handshakeTimeoutMs: e.handshakeTimeoutMs ?? 1e4
+    };
+    if ((e.mode ?? "tunnel") === "tunnel") {
+      const p = e.grant ?? (e.controlplane ? await W(e.controlplane) : null);
+      if (!p)
+        throw new Error("Tunnel mode requires `grant` or `controlplane` config");
+      return t(p, n);
+    }
+    if (!e.directInfo)
+      throw new Error("Direct mode requires `directInfo`");
+    return o(e.directInfo, n);
+  }, x = async (r, e) => {
+    const t = y(e.autoReconnect);
+    let o = 0;
+    for (; ; ) {
+      if (r !== l || u !== e) return;
+      o += 1;
+      try {
+        const n = await f(r, e);
+        if (r !== l) {
+          n.close();
+          return;
+        }
+        if (u !== e) {
+          n.close();
+          return;
+        }
+        i({
+          status: "connected",
+          client: n,
+          error: null
+        });
+        return;
+      } catch (n) {
+        const s = n instanceof Error ? n : new Error(String(n));
+        if (r !== l || u !== e) return;
+        if (!(t.enabled && o < t.maxAttempts))
+          throw i({
+            status: "error",
+            error: s,
+            client: null
+          }), s;
+        i({
+          status: "connecting",
+          error: s,
+          client: null
+        });
+        const D = j(o - 1, t);
+        await b(D);
+      }
+    }
+  }, v = {
+    status: () => c.status,
+    error: () => c.error,
+    client: () => c.client,
+    connect: async (r) => {
+      h(), l += 1;
+      const e = l;
+      u = r, c.client && c.client.close(), i({
+        status: "connecting",
+        error: null,
+        client: null
+      }), await x(e, r);
+    },
+    disconnect: () => {
+      M();
+    }
+  };
+  return E(() => {
+    M();
+  }), P(R.Provider, {
+    value: v,
+    get children() {
+      return a.children;
+    }
+  });
+}
+function N() {
+  const a = k(R);
+  if (!a)
+    throw new Error("useProtocol must be used within a ProtocolProvider");
+  return a;
+}
+export {
+  H as ProtocolProvider,
+  N as useProtocol
+};

package/dist/index3.js

@@ -0,0 +1,56 @@
+var i = Object.defineProperty;
+var p = (o, e, r) => e in o ? i(o, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : o[e] = r;
+var s = (o, e, r) => p(o, typeof e != "symbol" ? e + "" : e, r);
+import { useProtocol as E } from "./index2.js";
+import { TypeIds as c } from "./index5.js";
+class u extends Error {
+  constructor() {
+    super("Not connected"), this.name = "ProtocolNotConnectedError";
+  }
+}
+class a extends Error {
+  constructor(r) {
+    super(r.message ?? `RPC error: ${r.code}`, { cause: r.cause });
+    s(this, "typeId");
+    s(this, "code");
+    this.name = "RpcError", this.typeId = r.typeId, this.code = r.code;
+  }
+}
+function w() {
+  const o = E(), e = async (r, d) => {
+    const n = o.client();
+    if (!n)
+      throw new u();
+    let t;
+    try {
+      t = await n.rpc.call(r, d);
+    } catch (l) {
+      throw new a({ typeId: r, code: -1, message: "RPC transport error", cause: l });
+    }
+    if (t.error)
+      throw new a({
+        typeId: r,
+        code: t.error.code,
+        message: t.error.message ?? `RPC error: ${t.error.code}`,
+        cause: t.error
+      });
+    return t.payload;
+  };
+  return {
+    // File system operations
+    fs: {
+      list: (r) => e(c.FS_LIST, r),
+      readFile: (r) => e(c.FS_READ_FILE, r),
+      writeFile: (r) => e(c.FS_WRITE_FILE, r),
+      delete: (r) => e(c.FS_DELETE, r),
+      getHome: () => e(c.FS_GET_HOME, {})
+    },
+    // Raw call for custom operations
+    call: e
+  };
+}
+export {
+  u as ProtocolNotConnectedError,
+  a as RpcError,
+  w as useRpc
+};

package/dist/index4.js

@@ -0,0 +1,17 @@
+import { assertChannelInitGrant as r } from "@floegence/flowersec-core";
+async function a(e) {
+  const t = await fetch(`${e.baseUrl}/v1/channel/init`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ endpoint_id: e.endpointId })
+  });
+  if (!t.ok)
+    throw new Error(`Failed to get channel grant: ${t.status}`);
+  const n = await t.json();
+  if (!(n != null && n.grant_client))
+    throw new Error("Invalid controlplane response: missing `grant_client`");
+  return r(n.grant_client);
+}
+export {
+  a as requestChannelGrant
+};

package/dist/index5.js

@@ -0,0 +1,28 @@
+const E = {
+  // File system operations
+  FS_LIST: 1001,
+  FS_READ_FILE: 1002,
+  FS_WRITE_FILE: 1003,
+  FS_DELETE: 1006,
+  FS_GET_HOME: 1010
+}, S = {
+  // File system operations
+  FS_CREATE_FILE: 1004,
+  FS_CREATE_DIR: 1005,
+  FS_RENAME: 1007,
+  FS_MOVE: 1008,
+  FS_COPY: 1009,
+  // Terminal operations
+  TERMINAL_SESSION_CREATE: 2001,
+  TERMINAL_SESSION_LIST: 2002,
+  TERMINAL_SESSION_ATTACH: 2003,
+  TERMINAL_DATA: 2004,
+  // Bidirectional notification
+  // System operations
+  SYSTEM_INFO: 3001,
+  SYSTEM_EXEC: 3002
+};
+export {
+  S as ReservedTypeIds,
+  E as TypeIds
+};

package/dist/rpc.d.ts

@@ -0,0 +1,29 @@
+import { type ListRequest, type ListResponse, type ReadFileRequest, type ReadFileResponse, type WriteFileRequest, type WriteFileResponse, type DeleteRequest, type DeleteResponse } from './types';
+/**
+ * RPC wrapper for type-safe remote calls
+ */
+export declare class ProtocolNotConnectedError extends Error {
+    constructor();
+}
+export declare class RpcError extends Error {
+    readonly typeId: number;
+    readonly code: number;
+    constructor(args: {
+        typeId: number;
+        code: number;
+        message?: string;
+        cause?: unknown;
+    });
+}
+export declare function useRpc(): {
+    fs: {
+        list: (req: ListRequest) => Promise<ListResponse>;
+        readFile: (req: ReadFileRequest) => Promise<ReadFileResponse>;
+        writeFile: (req: WriteFileRequest) => Promise<WriteFileResponse>;
+        delete: (req: DeleteRequest) => Promise<DeleteResponse>;
+        getHome: () => Promise<{
+            path: string;
+        }>;
+    };
+    call: <Req, Res>(typeId: number, request: Req) => Promise<Res>;
+};

package/dist/types/common.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Common type definitions for the protocol layer
+ */
+/**
+ * Type IDs that are currently implemented by `useRpc()`.
+ *
+ * Keep this list aligned with `packages/protocol/src/rpc.ts` to avoid misleading downstream users.
+ */
+export declare const TypeIds: {
+    readonly FS_LIST: 1001;
+    readonly FS_READ_FILE: 1002;
+    readonly FS_WRITE_FILE: 1003;
+    readonly FS_DELETE: 1006;
+    readonly FS_GET_HOME: 1010;
+};
+/**
+ * Reserved Type IDs for future protocol domains.
+ *
+ * These are part of the protocol contract, but are not yet exposed via `useRpc()`.
+ */
+export declare const ReservedTypeIds: {
+    readonly FS_CREATE_FILE: 1004;
+    readonly FS_CREATE_DIR: 1005;
+    readonly FS_RENAME: 1007;
+    readonly FS_MOVE: 1008;
+    readonly FS_COPY: 1009;
+    readonly TERMINAL_SESSION_CREATE: 2001;
+    readonly TERMINAL_SESSION_LIST: 2002;
+    readonly TERMINAL_SESSION_ATTACH: 2003;
+    readonly TERMINAL_DATA: 2004;
+    readonly SYSTEM_INFO: 3001;
+    readonly SYSTEM_EXEC: 3002;
+};
+export interface FileInfo {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    size: number;
+    modifiedAt: number;
+    createdAt: number;
+    permissions?: string;
+}
+export interface ListRequest {
+    path: string;
+    showHidden?: boolean;
+}
+export interface ListResponse {
+    entries: FileInfo[];
+}
+export interface ReadFileRequest {
+    path: string;
+    encoding?: 'utf8' | 'base64';
+}
+export interface ReadFileResponse {
+    content: string;
+    encoding: string;
+}
+export interface WriteFileRequest {
+    path: string;
+    content: string;
+    encoding?: 'utf8' | 'base64';
+    createDirs?: boolean;
+}
+export interface WriteFileResponse {
+    success: boolean;
+}
+export interface DeleteRequest {
+    path: string;
+    recursive?: boolean;
+}
+export interface DeleteResponse {
+    success: boolean;
+}
+export interface TerminalSession {
+    id: string;
+    name?: string;
+    cols: number;
+    rows: number;
+    pid?: number;
+}
+export interface CreateTerminalRequest {
+    name?: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface CreateTerminalResponse {
+    session: TerminalSession;
+}
+export interface TerminalDataPayload {
+    sessionId: string;
+    data: Uint8Array;
+}
+export interface TerminalResizePayload {
+    sessionId: string;
+    cols: number;
+    rows: number;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from './common';

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@floegence/floe-webapp-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "pnpm clean && vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.8.0"
+  },
+  "dependencies": {
+    "@floegence/flowersec-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "solid-js": "^1.9.3",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.7",
+    "vite-plugin-solid": "^2.11.0"
+  }
+}