@owncast/plugin-sdk 0.4.0 → 0.4.1

package/bin/owncast-plugin.js

@@ -398,6 +398,13 @@ function generateInterface(manifest) {
   if (perms.has("storage.upload")) {
     imports.push("owncast_storage_upload(namePtr: PTR, dataPtr: PTR): PTR");
   }
+  if (perms.has("storage.fs")) {
+    imports.push("owncast_fs_read(pathPtr: PTR): PTR");
+    imports.push("owncast_fs_write(pathPtr: PTR, dataPtr: PTR): PTR");
+    imports.push("owncast_fs_list(dirPtr: PTR): PTR");
+    imports.push("owncast_fs_delete(pathPtr: PTR): PTR");
+    imports.push("owncast_fs_exists(pathPtr: PTR): I32");
+  }
   if (perms.has("fediverse.post")) {
     imports.push("owncast_fediverse_post(textPtr: PTR): PTR");
   }

package/index.d.ts

@@ -115,6 +115,8 @@ export const Events: {
   readonly StreamStarted: "stream.started";
   readonly StreamStopped: "stream.stopped";
   readonly StreamTitleChanged: "stream.title.changed";
+  readonly SseConnect: "sse.connect";
+  readonly SseDisconnect: "sse.disconnect";
   readonly FediverseFollow: "fediverse.follow";
   readonly FediverseLike: "fediverse.like";
   readonly FediverseRepost: "fediverse.repost";
@@ -161,6 +163,7 @@ export const Permissions: {
   readonly ChatFilter: "chat.filter";
   readonly StorageKV: "storage.kv";
   readonly StorageUpload: "storage.upload";
+  readonly StorageFS: "storage.fs";
   readonly EventsEmit: "events.emit";
   readonly NetworkFetch: "network.fetch";
   readonly HttpServe: "http.serve";
@@ -228,6 +231,13 @@ export interface UploadResult {
   url: string;
 }
 
+/** Result of a mutating owncast.fs call (write/delete). `ok` is false and
+ *  `error` is set when the host rejected the operation. */
+export interface FsResult {
+  ok: boolean;
+  error?: string;
+}
+
 export const filter: {
   pass(): FilterResult;
   modify(payload: any): FilterResult;
@@ -256,6 +266,18 @@ export interface OutgoingHttpResponse {
   body?: string;
 }
 
+/** Payload for the sse.connect / sse.disconnect events. Fired when a browser
+ *  opens or closes one of the plugin's `/plugins/<name>/_sse/<channel>`
+ *  streams, so the plugin can track who is connected. `connectionId` is unique
+ *  per connection for the life of the host process, so a disconnect can be
+ *  paired with its connect and the same user counted across several tabs.
+ *  `user` is present only when the connection carried a chat identity. */
+export interface SSEConnectionEvent {
+  channel: string;
+  connectionId: number;
+  user?: ChatUser;
+}
+
 export interface PluginDef {
   /** Notification handler for chat messages. Fire-and-forget. */
   onChatMessage?(msg: ChatMessage): void | Promise<void>;
@@ -280,6 +302,13 @@ export interface PluginDef {
   /** Stream title was updated. */
   onStreamTitleChanged?(change: StreamTitleChange): void | Promise<void>;
 
+  /** A browser opened one of this plugin's SSE streams. Use it to track who
+   *  is connected. Requires the `http.sse` permission. */
+  onSseConnect?(event: SSEConnectionEvent): void | Promise<void>;
+  /** A browser closed one of this plugin's SSE streams (same connectionId as
+   *  the matching onSseConnect). Requires the `http.sse` permission. */
+  onSseDisconnect?(event: SSEConnectionEvent): void | Promise<void>;
+
   /** Someone on the fediverse followed the streamer's account. */
   onFediverseFollow?(event: FediverseEngagement): void | Promise<void>;
   /** Someone on the fediverse liked a streamer post / federated stream announcement. */
@@ -349,6 +378,23 @@ export const owncast: {
   storage: {
     upload(name: string, data: Uint8Array | string): UploadResult | null;
   };
+  /** Private, sandboxed filesystem under data/plugin-data/<slug>/. The bytes
+   *  stay server-side (never served over HTTP) and the host confines every
+   *  path to this plugin's own directory. All methods require `storage.fs`. */
+  fs: {
+    /** Read a file's raw bytes, or null if it doesn't exist. */
+    read(path: string): Uint8Array | null;
+    /** Read a file as UTF-8 text, or null if it doesn't exist. */
+    readText(path: string): string | null;
+    /** Write bytes or a string, creating parent directories as needed. */
+    write(path: string, data: Uint8Array | string): FsResult;
+    /** List entry names directly inside dir; missing dir lists as empty. */
+    list(dir: string): string[];
+    /** Remove a single file or empty directory. */
+    delete(path: string): FsResult;
+    /** Report whether a path exists inside the sandbox. */
+    exists(path: string): boolean;
+  };
   /** Post to the fediverse on the streamer's behalf. Requires `fediverse.post`,
    *  which is high-trust (posts go out under the streamer's own handle);
    *  admins should grant it sparingly. */

package/index.js

@@ -24,6 +24,9 @@ const Events = Object.freeze({
   StreamStarted: "stream.started",
   StreamStopped: "stream.stopped",
   StreamTitleChanged: "stream.title.changed",
+  // SSE connection lifecycle (who connected to / left a plugin's stream)
+  SseConnect: "sse.connect",
+  SseDisconnect: "sse.disconnect",
   // Fediverse, engagement (metadata only) + inbound posts (with content)
   FediverseFollow: "fediverse.follow",
   FediverseLike: "fediverse.like",
@@ -39,6 +42,7 @@ const Permissions = Object.freeze({
   ChatFilter: "chat.filter",
   StorageKV: "storage.kv",
   StorageUpload: "storage.upload",
+  StorageFS: "storage.fs",
   EventsEmit: "events.emit",
   NetworkFetch: "network.fetch",
   HttpServe: "http.serve",
@@ -102,6 +106,9 @@ const HANDLERS = Object.freeze({
     event: Events.StreamTitleChanged,
     kind: HandlerKind.Notify,
   },
+  // SSE connection lifecycle
+  onSseConnect: { event: Events.SseConnect, kind: HandlerKind.Notify },
+  onSseDisconnect: { event: Events.SseDisconnect, kind: HandlerKind.Notify },
   // Fediverse engagement (actor + target metadata)
   onFediverseFollow: {
     event: Events.FediverseFollow,
@@ -341,6 +348,80 @@ const owncast = {
       return JSON.parse(Memory.find(offset).readString());
     },
   },
+  // Private, sandboxed filesystem under data/plugin-data/<slug>/. Unlike
+  // storage.upload (which publishes browser-accessible files), these bytes
+  // stay server-side. The host confines every path to this plugin's own
+  // directory. All methods require the 'storage.fs' permission.
+  fs: {
+    // Read a file's raw bytes. Returns a Uint8Array, or null if the file
+    // doesn't exist (or can't be read).
+    read(path) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_read)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const offset = fns.owncast_fs_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return new Uint8Array(Memory.find(offset).readBytes());
+    },
+    // Read a file as UTF-8 text. Returns a string, or null if the file
+    // doesn't exist. (The Extism boundary decodes the bytes as UTF-8.)
+    readText(path) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_read)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const offset = fns.owncast_fs_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return Memory.find(offset).readString();
+    },
+    // Write bytes (Uint8Array) or a string to a file, creating parent
+    // directories as needed. Returns { ok, error? }.
+    write(path, data) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_write)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const dataMem =
+        data instanceof Uint8Array
+          ? Memory.fromBuffer(
+              data.buffer.slice(
+                data.byteOffset,
+                data.byteOffset + data.byteLength,
+              ),
+            )
+          : Memory.fromString(String(data));
+      const offset = fns.owncast_fs_write(
+        Memory.fromString(path).offset,
+        dataMem.offset,
+      );
+      if (offset == 0) return { ok: false, error: "write failed" };
+      return JSON.parse(Memory.find(offset).readString());
+    },
+    // List the entry names (files and subdirectories) directly inside dir.
+    // A missing directory lists as empty. Returns string[].
+    list(dir) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_list)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const offset = fns.owncast_fs_list(Memory.fromString(dir || "").offset);
+      if (offset == 0) return [];
+      return JSON.parse(Memory.find(offset).readString());
+    },
+    // Remove a single file or empty directory. Returns { ok, error? }.
+    delete(path) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_delete)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const offset = fns.owncast_fs_delete(Memory.fromString(path).offset);
+      if (offset == 0) return { ok: false, error: "delete failed" };
+      return JSON.parse(Memory.find(offset).readString());
+    },
+    // Report whether a path exists inside the sandbox. Returns boolean.
+    exists(path) {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_fs_exists)
+        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      return fns.owncast_fs_exists(Memory.fromString(path).offset) === 1;
+    },
+  },
   fediverse: {
     /** Publish a public text-only post to the fediverse on the streamer's
      *  behalf. Returns { url } on success, null on failure (rate-limited,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owncast/plugin-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",