@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/plugos/syscalls/event.ts

@@ -9,25 +9,58 @@ export function eventSyscalls(
   client: Client,
 ): SysCallMapping {
   return {
-    "event.dispatch": (_ctx, eventName: string, data: any) => {
-      return eventHook.dispatchEvent(eventName, data);
+    "event.dispatch": {
+      callback: (_ctx, eventName: string, data: any) => {
+        return eventHook.dispatchEvent(eventName, data);
+      },
+      description:
+        "Dispatches an event and collects responses from its listeners.",
+      parameters: [
+        { name: "eventName", type: "string", description: "Event name." },
+        { name: "data", description: "Event payload." },
+      ],
+      returns: [{ type: "table", description: "Listener responses." }],
+      examples: [
+        {
+          code: 'local responses = event.dispatch("data.request", {id = 123})',
+        },
+      ],
     },
-    "event.listEvents": () => {
-      return eventHook.listEvents();
+    "event.listEvents": {
+      callback: () => {
+        return eventHook.listEvents();
+      },
+      description: "Lists all event names that currently have listeners.",
+      returns: [{ type: "table", description: "Registered event names." }],
     },
     /**
      * Define a Lua event listener
      */
-    "event.listen": (_ctx, def: EventSubscription) => {
-      // console.log("Registering Lua event listener: ", def.name);
-      client.config.insert(
-        ["eventListeners", def.name],
-        async (...args: any[]) => {
-          // Convert return value to JS
-          const val = await def.run(...args);
-          return luaValueToJS(val, LuaStackFrame.lostFrame);
+    "event.listen": {
+      callback: (_ctx, def: EventSubscription) => {
+        // console.log("Registering Lua event listener: ", def.name);
+        client.config.insert(
+          ["eventListeners", def.name],
+          async (...args: any[]) => {
+            // Convert return value to JS
+            const val = await def.run(...args);
+            return luaValueToJS(val, LuaStackFrame.lostFrame);
+          },
+        );
+      },
+      description: "Registers a Space Lua listener on the event bus.",
+      parameters: [
+        {
+          name: "listener",
+          type: "table",
+          description: "Listener definition with name and run callback.",
+        },
+      ],
+      examples: [
+        {
+          code: 'event.listen { name = "my-event", run = function(e) print(e.data) end }',
         },
-      );
+      ],
     },
   };
 }

package/client/plugos/syscalls/fetch.ts

@@ -15,91 +15,132 @@ import { fsEndpoint } from "../../spaces/constants.ts";
 export function sandboxFetchSyscalls(client: Client): SysCallMapping {
   return {
     // For use in Lua
-    "http.request": async (
-      _ctx,
-      url: string,
-      options: ProxyFetchRequest = {},
-    ): Promise<ProxyFetchResponse> => {
-      console.warn("Deprecated: use net.proxyFetch() instead");
-      // JSONify any non-serializable body
-      if (
-        options?.body &&
-        typeof options.body !== "string" &&
-        !(options.body instanceof Uint8Array)
-      ) {
-        options.body = JSON.stringify(options.body);
-      }
-      const fetchOptions = options
-        ? {
-            method: options.method,
-            headers: {} as Record<string, string>,
-            body: options.body,
-          }
-        : {};
+    "http.request": {
+      callback: async (
+        _ctx,
+        url: string,
+        options: ProxyFetchRequest = {},
+      ): Promise<ProxyFetchResponse> => {
+        console.warn("Deprecated: use net.proxyFetch() instead");
+        // JSONify any non-serializable body
+        if (
+          options?.body &&
+          typeof options.body !== "string" &&
+          !(options.body instanceof Uint8Array)
+        ) {
+          options.body = JSON.stringify(options.body);
+        }
+        const fetchOptions = options
+          ? {
+              method: options.method,
+              headers: {} as Record<string, string>,
+              body: options.body,
+            }
+          : {};
 
-      fetchOptions.headers = buildProxyHeaders(options?.headers);
+        fetchOptions.headers = buildProxyHeaders(options?.headers);
 
-      const resp = await client.httpSpacePrimitives.authenticatedFetch(
-        buildProxyUrl(client, url),
-        fetchOptions,
-      );
-      // Do sensible things with the body based on the content type
-      // Read as ArrayBuffer first to safely handle empty responses (e.g.
-      // PUT/DELETE returning 204 with Content-Type: application/json).
-      // resp.arrayBuffer() never throws on an empty body, whereas
-      // resp.json() would throw a SyntaxError.
-      const rawBytes = new Uint8Array(await resp.arrayBuffer());
-      let body: any;
-      const contentTypeHeader =
-        options.responseEncoding ||
-        resp.headers.get("x-proxy-header-content-type");
-      const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
-      if (rawBytes.length === 0) {
-        body = null;
-      } else if (contentTypeHeader?.startsWith("application/json")) {
-        body = JSON.parse(new TextDecoder().decode(rawBytes));
-      } else if (
-        contentTypeHeader?.startsWith("application/xml") ||
-        contentTypeHeader?.startsWith("text/")
-      ) {
-        body = new TextDecoder().decode(rawBytes);
-      } else {
-        body = rawBytes;
-      }
-      return {
-        ok: resp.ok,
-        status: statusCode,
-        headers: extractProxyHeaders(resp.headers),
-        body: body,
-      };
+        const resp = await client.httpSpacePrimitives.authenticatedFetch(
+          buildProxyUrl(client, url),
+          fetchOptions,
+        );
+        // Do sensible things with the body based on the content type
+        // Read as ArrayBuffer first to safely handle empty responses (e.g.
+        // PUT/DELETE returning 204 with Content-Type: application/json).
+        // resp.arrayBuffer() never throws on an empty body, whereas
+        // resp.json() would throw a SyntaxError.
+        const rawBytes = new Uint8Array(await resp.arrayBuffer());
+        let body: any;
+        const contentTypeHeader =
+          options.responseEncoding ||
+          resp.headers.get("x-proxy-header-content-type");
+        const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
+        if (rawBytes.length === 0) {
+          body = null;
+        } else if (contentTypeHeader?.startsWith("application/json")) {
+          body = JSON.parse(new TextDecoder().decode(rawBytes));
+        } else if (
+          contentTypeHeader?.startsWith("application/xml") ||
+          contentTypeHeader?.startsWith("text/")
+        ) {
+          body = new TextDecoder().decode(rawBytes);
+        } else {
+          body = rawBytes;
+        }
+        return {
+          ok: resp.ok,
+          status: statusCode,
+          headers: extractProxyHeaders(resp.headers),
+          body: body,
+        };
+      },
+      description:
+        "Performs an authenticated HTTP request through the server proxy.",
+      parameters: [
+        { name: "url", type: "string", description: "Target URL." },
+        {
+          name: "options",
+          type: "table",
+          description: "Method, headers, body, and response encoding.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Status, headers, and decoded response body.",
+        },
+      ],
+      deprecated: "Use net.proxyFetch instead.",
+      see: "API/net#net.proxyFetch(url, options?)",
     },
-    "sandboxFetch.fetch": async (
-      _ctx,
-      url: string,
-      options?: ProxyFetchRequest64,
-    ): Promise<ProxyFetchResponse64> => {
-      // console.log("Got sandbox fetch ", url, op);
-      const fetchOptions = options
-        ? {
-            method: options.method,
-            headers: options.headers,
-            body: options.base64Body && base64Decode(options.base64Body),
-          }
-        : {};
-      fetchOptions.headers = buildProxyHeaders(options?.headers);
-      const resp = await client.httpSpacePrimitives.authenticatedFetch(
-        buildProxyUrl(client, url),
-        // Casting to any due to TypeScript fetch type limitations
-        fetchOptions as any,
-      );
-      const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
-      const body = await resp.arrayBuffer();
-      return {
-        ok: resp.ok,
-        status: statusCode,
-        headers: extractProxyHeaders(resp.headers),
-        base64Body: base64Encode(new Uint8Array(body)),
-      };
+    "sandboxFetch.fetch": {
+      callback: async (
+        _ctx,
+        url: string,
+        options?: ProxyFetchRequest64,
+      ): Promise<ProxyFetchResponse64> => {
+        // console.log("Got sandbox fetch ", url, op);
+        const fetchOptions = options
+          ? {
+              method: options.method,
+              headers: options.headers,
+              body: options.base64Body && base64Decode(options.base64Body),
+            }
+          : {};
+        fetchOptions.headers = buildProxyHeaders(options?.headers);
+        const resp = await client.httpSpacePrimitives.authenticatedFetch(
+          buildProxyUrl(client, url),
+          // Casting to any due to TypeScript fetch type limitations
+          fetchOptions as any,
+        );
+        const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
+        const body = await resp.arrayBuffer();
+        return {
+          ok: resp.ok,
+          status: statusCode,
+          headers: extractProxyHeaders(resp.headers),
+          base64Body: base64Encode(new Uint8Array(body)),
+        };
+      },
+      description:
+        "Performs an authenticated proxied fetch for a plug sandbox.",
+      parameters: [
+        { name: "url", type: "string", description: "Target URL." },
+        {
+          name: "options",
+          type: "table",
+          description: "Method, headers, and base64-encoded body.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Status, headers, and base64-encoded response body.",
+        },
+      ],
+      see: "API/http",
     },
   };
 }