mainasara.dev / streamplace-vod
An entry for the streamplace vod showcase
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

streamplace-vod / DESIGN.md
at main 7.8 kB view raw view code
neutrino2211 docs: add comprehensive documentation for all components
1b17d33a

Design Decisions#

This document captures the key architectural decisions made while building the at-run serverless execution system and AtmosphereConf VOD app. Decisions are attributed to who drove them.

Core Architecture#

Serverless on AT Protocol (Mainasara)#

The foundational idea: store JavaScript bundles as blobs on your PDS, execute them via runners. "Your code is your data." This enables decentralized compute where anyone can run a runner and execute bundles from any PDS.

Deno Sandbox (Claude)#

Use Deno subprocess for sandboxed execution instead of Bun's unsafe import(). Deno's permission model (--allow-net, --allow-read, etc.) maps cleanly to bundle-declared permissions, providing security without complex VM isolation.

Manifest + Endpoint Pattern (Claude)#

Bundle authors declare a manifest() with permissions and endpoint() functions with handlers. The runner extracts this metadata at load time and enforces permissions at execution time.

export const bundle = manifest({
  name: "my-api",
  permissions: { net: ["api.example.com"] },
})

export const getData = endpoint({
  handler: async () => { ... },
})

Secrets Encryption (Claude)#

Secrets are encrypted with the runner's public key using X25519-XSalsa20-Poly1305. Bundle authors encrypt secrets for specific runners, stored on-chain. Runners decrypt at execution time and inject as environment variables. This keeps secrets safe even though bundles are public.

Env Permissions Derived from Secrets (Mainasara)#

Rather than bundle authors declaring which env vars they need, derive --allow-env permissions automatically from the secrets configured for that bundle on each runner. Simpler and more secure.

Task System#

Background Jobs with Concurrency Limiting (Mainasara)#

Heavy operations like thumbnail generation were killing the $5 VPS. The user requested a "job paradigm" - something that queues work and returns status.

Task Abstraction (Claude)#

Implemented task() as a variant of endpoint() with:

  • concurrency: max parallel executions (prevents resource exhaustion)
  • cacheTtl: result caching (avoids redundant work)
  • Input-based deduplication (same args = same task)

Clients get { status: "pending" | "running" | "complete", result?: ... } and retry until complete.

export const videoMetadata = task({
  concurrency: 2,
  cacheTtl: 86400,  // 24h
  handler: async ({ uri }) => { ... },
})

Client Polling (Claude)#

Web client uses callTask() helper that retries every 2 seconds until status is "complete". Simple and works with any HTTP client.

Video Processing#

HLS Streaming (Mainasara)#

Use stream.place's existing HLS infrastructure. The VOD bundle fetches playlists, rewrites relative URLs to absolute, and serves to video players.

URL Rewriting for Local FFmpeg (Claude)#

HLS playlists use relative URLs. For ffmpeg to process them locally, rewrite all segment URLs to absolute (https://vod-beta.stream.place/xrpc/...).

Sprite Sheet Hover Previews (Mainasara)#

YouTube-style thumbnail previews on hover. User wanted this specific UX.

Sprite Implementation (Claude)#

Generate 8 frames at even intervals, combine into 4x2 grid using ffmpeg's xstack filter. Output WebVTT with #xywh= coordinates for each frame's position. Web component parses VTT and cycles through frames on hover.

2x Quality Sprites (Mainasara)#

Initial 160x90 frames looked blurry. User requested 320x180 for sharper previews.

Accelerator Architecture#

Offload to Serverless GPU (Mainasara)#

The $5 VPS couldn't handle ffmpeg thumbnail generation at scale. User suggested Modal/RunPod with GPU acceleration.

Runner as Gateway, Modal as Compute (Claude)#

Keep the runner as a lightweight API gateway handling:

  • Task queue (deduplication, caching)
  • Request routing
  • Secrets management

Offload heavy compute to Modal. The task just calls Modal's endpoint and returns the result.

Frontend-Side Processing with MediaBunny (Mainasara)#

After debugging CUDA/ffmpeg image issues on Modal, decided to handle video processing from the frontend using mediabunny.dev instead of server-side acceleration.

Web App#

YouTube-Style Layout (Mainasara)#

User requested a layout matching YouTube's player page: video on left, metadata and related content on right.

Fixed Aspect Ratio Container (Claude)#

Use aspect-ratio: 16/9 on the video container to prevent layout shift when the video loads.

Creator Profiles from Bluesky (Mainasara)#

Show the video creator's Bluesky profile (avatar, display name) on the video page.

Profile Endpoint (Claude)#

Add getProfile endpoint that fetches from public.api.bsky.app and returns normalized profile data.

Deployment#

Docker with Bun + Deno + FFmpeg (Claude)#

Single Dockerfile that installs all three runtimes. Runner uses Bun for the HTTP server, spawns Deno for sandboxed execution.

Volume Mount for Keys (Mainasara)#

Runner keys stored at ~/.at-run/ on the host, mounted read-only into the container. User specified this path.

Dokploy Deployment (Mainasara)#

User's platform of choice for Docker deployments.

Social Sharing#

Share Endpoints Pattern (Mainasara)#

For rich link previews in a static SPA, create server endpoints that return HTML with OG meta tags then redirect to the frontend. The share button copies a link to the server endpoint, not the SPA route.

Simplified OG Images (Claude, with Mainasara's direction)#

Initially attempted satori-based OG image generation with custom fonts and layouts. Encountered WASM initialization issues in the Deno sandbox. Simplified to using original thumbnails/avatars directly as OG images, with titles formatted as "Streamhut | <title>".

Runner Improvements#

Dynamic Imports for Sandbox Compatibility (Claude)#

Libraries that access process.env at import time break bundle extraction. Solution: use dynamic import() inside handlers so the code only runs after permissions are applied.

Merge Env Permissions with Secrets (Claude)#

Runner was replacing bundle's declared env permissions with only secret keys. Fixed to merge both - bundles can declare env vars they need (e.g., JEST_WORKER_ID for satori) while also getting their secrets.

Don't Cache "Latest" Version Resolution (Claude)#

The runner was caching did/name/latest -> specific AT URI. After deploying a new version, old URI was served until restart. Fixed by skipping cache when version is "latest".

Robust Version Sorting (Claude)#

Use parseInt() instead of Number() for parsing version strings. Handles edge cases like "1.2.3-beta" correctly.

Lessons Learned#

  1. Start simple, add complexity when needed: Began with synchronous endpoints, added task queue only when resource exhaustion became a problem.

  2. Platform ffmpeg builds don't include CUDA: Getting GPU-accelerated ffmpeg requires custom builds or specialized images. Sometimes it's easier to use a managed service.

  3. Env access at module load time breaks extraction: The runner extracts bundle metadata in a minimal sandbox. Any code that runs at import time (like Deno.env.get()) must be deferred to handler execution.

  4. HLS + ffmpeg + seeking is tricky: Accurate seeking in HLS streams requires -ss after -i, not before. Seek times must be clamped to video duration.

  5. User-Agent matters: Some APIs return 403 without a proper User-Agent header. Always set one when making HTTP requests from serverless functions.

  6. Keep OG images simple: Generated images with custom fonts require WASM, font fetching, and complex rendering. Using existing thumbnails/avatars is more reliable and the result is often better anyway.