@owncast/plugin-sdk 0.3.1 → 0.4.1

package/bin/owncast-plugin.js

@@ -238,50 +238,18 @@ module.exports = { register, on_event, on_filter, on_http_request };
     env,
   });
 
-  // If the project ships static assets in ./assets/, mirror them to the
-  // canonical deployment layout (<name>-assets/) so plugin.Server finds them
-  // without per-deployment renames. We use a symlink so edits to assets/
-  // show up live during dev (no rebuild needed for HTML/CSS changes).
-  const assetsSrc = path.join(cwd, "assets");
-  if (fs.existsSync(assetsSrc) && fs.statSync(assetsSrc).isDirectory()) {
-    const assetsDest = path.join(cwd, `${slug}-assets`);
-    let needsLink = true;
-    // Use lstatSync (not existsSync), existsSync follows symlinks and
-    // returns false for a dangling link, but the link's inode is still
-    // there and would make symlinkSync below fail with EEXIST. lstatSync
-    // sees the link itself regardless of whether its target resolves.
-    let st;
-    try {
-      st = fs.lstatSync(assetsDest);
-    } catch {
-      // path doesn't exist at all, fall through to create it.
-    }
-    if (st) {
-      let target;
-      if (st.isSymbolicLink()) {
-        // realpathSync throws on dangling links; treat that as "doesn't
-        // match, replace it" rather than letting it abort the build.
-        try {
-          target = fs.realpathSync(assetsDest);
-        } catch {}
-      }
-      if (target && target === fs.realpathSync(assetsSrc)) {
-        needsLink = false;
-      } else {
-        fs.rmSync(assetsDest, { recursive: true, force: true });
-      }
-    }
-    if (needsLink) {
-      fs.symlinkSync(path.resolve(assetsSrc), assetsDest, "dir");
-    }
-  }
+  // public/ and assets/ live at the source root; the host's
+  // loose-files loader picks them up as siblings of the built
+  // <slug>.wasm without any rename, so the build CLI doesn't need to
+  // create or mirror anything for them.
 
   console.log(`built ${path.relative(cwd, wasmOut)}`);
 }
 
 // `owncast-plugin package`, bundle the project into a single .ocpkg file
-// (zip archive with plugin.manifest.json, plugin.wasm, and optional assets/).
-// Builds the wasm first if it doesn't exist.
+// (zip archive with plugin.manifest.json, plugin.wasm, and optional
+// public/ and assets/ directories). Builds the wasm first if it
+// doesn't exist.
 async function packageMain() {
   const cwd = process.cwd();
   const manifestPath = path.join(cwd, "plugin.manifest.json");
@@ -296,6 +264,7 @@ async function packageMain() {
     await buildMain();
   }
 
+  const publicDir = path.join(cwd, "public");
   const assetsDir = path.join(cwd, "assets");
   const zip = new JSZip();
   zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
@@ -310,6 +279,26 @@ async function packageMain() {
     zip.file("icon.png", fs.readFileSync(iconPath));
     fileCount++;
   }
+  // Bundle a top-level INSTRUCTIONS.md if the plugin source root has one.
+  // The host serves it to the admin (which renders it as markdown in a
+  // details tab); like icon.png it needs no manifest field and no
+  // http.serve permission. The filename is fixed for simplicity.
+  const instructionsPath = path.join(cwd, "INSTRUCTIONS.md");
+  if (fs.existsSync(instructionsPath) && fs.statSync(instructionsPath).isFile()) {
+    zip.file("INSTRUCTIONS.md", fs.readFileSync(instructionsPath));
+    fileCount++;
+  }
+  // public/ → /plugins/<slug>/<path>, served by the host.
+  if (fs.existsSync(publicDir) && fs.statSync(publicDir).isDirectory()) {
+    for (const file of walkFiles(publicDir)) {
+      const rel = path.relative(publicDir, file).split(path.sep).join("/");
+      zip.file(`public/${rel}`, fs.readFileSync(file));
+      fileCount++;
+    }
+  }
+  // assets/ → host reads internally for manifest fields that inline
+  // file contents (styles, scripts, extraPageContent). Not served at
+  // a URL.
   if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
     for (const file of walkFiles(assetsDir)) {
       const rel = path.relative(assetsDir, file).split(path.sep).join("/");
@@ -329,12 +318,29 @@ async function packageMain() {
   console.log(
     `packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`,
   );
+
+  // Drop the intermediate <slug>.wasm now that it's bundled inside the
+  // .ocpkg. The .ocpkg is the only artifact authors care about: leaving
+  // the loose .wasm next to it just confuses "what do I ship". Only
+  // runs on a successful package so a mid-pipeline failure leaves the
+  // last good build in place for debugging.
+  try {
+    fs.unlinkSync(wasmPath);
+  } catch (e) {
+    // Don't fail the package step over a cleanup miss. The .ocpkg is
+    // already written; surface the warning so the author notices the
+    // straggler but treat the run as successful.
+    if (e.code !== "ENOENT") {
+      console.warn(`warning: could not clean up ${path.relative(cwd, wasmPath)}: ${e.message}`);
+    }
+  }
 }
 
 function* walkFiles(dir) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    // Resolve symlinks so the assets/ → <name>-assets/ link the build CLI
-    // makes doesn't cause us to skip files. statSync follows.
+    // statSync (not lstatSync) so a symlinked file or directory in
+    // the source tree resolves to its target and we read its contents
+    // rather than skipping it.
     const full = path.join(dir, entry.name);
     let info;
     try {
@@ -392,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.3.1",
+  "version": "0.4.1",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",