@arsenstorm/olos

OLOS

Open Live Object Streaming protocol primitives. A low-latency append-only stream log over plain object storage (S3, R2, GCS).

Install

npm install @arsenstorm/olos

Imports

import { OLOS_PROTOCOL_NAME, OLOS_WIRE_VERSION } from "@arsenstorm/olos";
import type { Session } from "@arsenstorm/olos/types";

Subpath	Use for
@arsenstorm/olos/runtime	Session routes, publisher loops, HLS serving.
@arsenstorm/olos/s3	S3 upload grants, observation, events, recovery, retention.
@arsenstorm/olos/hls	HLS rendering and blocking-reload helpers.
@arsenstorm/olos/protocol	Coordinator stores and adapter conformance.
@arsenstorm/olos/state	Lower-level state transitions and policies.
@arsenstorm/olos/schema	JSON Schemas for wire objects.
@arsenstorm/olos/validation	Runtime payload validators.
@arsenstorm/olos/types	Public protocol data types.
@arsenstorm/olos/config	Protocol constants and policy defaults.
@arsenstorm/olos/conformance	Assertion metadata and store checks.

Quick start

A complete OLOS endpoint with S3-backed live media:

import {
  createMemorySerializedCoordinatorStoreBackend,
  createSerializedCoordinatorStore,
} from "@arsenstorm/olos/protocol";
import { createStoredS3CoordinatorRuntimeHandler } from "@arsenstorm/olos/s3";
import { S3Client } from "@aws-sdk/client-s3";

const store = createSerializedCoordinatorStore(
  createMemorySerializedCoordinatorStoreBackend()
);

const s3 = new S3Client({ region: "us-east-1" });

const handleOlos = createStoredS3CoordinatorRuntimeHandler({
  allowedMediaOrigins: ["https://media.example.com"],
  bucket: "olos-media",
  client: s3,
  expiresInSeconds: 5,
  providerId: "s3_primary",
  store,
});

export default { fetch: (req: Request) => handleOlos(req) };

Publishers create a session, then loop: get a presigned slot, PUT media bytes to S3, post a commit. Viewers GET HLS manifests. The handler covers it.

Working setups:

• examples/api — Cloudflare Worker + Durable Object + R2.
• examples/streamer — OBS-to-OLOS bridge using ffmpeg micro-segments.
• examples/player — LL-HLS player at the PART-HOLD-BACK spec floor.

Routes

The handler mounts:

Method	Path	Purpose
POST	/sessions	Create a session.
POST	/sessions/:id/s3/slots	Issue a presigned upload slot.
POST	/sessions/:id/s3/commits	Observe and commit an upload.
POST	/sessions/:id/s3/events	Accept S3 object-created events.
POST	/sessions/:id/s3/reconcile-plan	List in-flight slots for recovery.
POST	/sessions/:id/s3/reconcile	Recover slots after missed events.
POST	/sessions/:id/s3/retention	Plan and delete retired media.
POST	/sessions/:id/transition	Advance session state.
POST	/sessions/:id/heartbeat	Publisher liveness ping.
GET	/sessions/:id/health	Live / starting / stale summary.
GET	/v1/live/:id/.../media.m3u8	LL-HLS playlist with _HLS_msn blocking reload.

Scope

OLOS owns slot rules, commit idempotency, S3 object observation, cursor sequencing, manifest rendering, retention planning, blocking-reload boundary, and the conformance suite.

Your app owns authentication, the coordinator store backend, S3 credentials, cursor wake-up mechanism, publisher scheduling, viewer routing, cache purge, and tenant quotas.

Beyond video

The core — slot, commit, cursor, blocking-read — is media-agnostic. LL-HLS is one binding. The same substrate could carry audio-only streams, captions, AI inference output, telemetry tails, or any append-only stream over object storage. Only the HLS rendering module assumes video.

Further reading

• Production pipeline — wiring a real deployment.
• Store adapters — coordinator store on SQL, KV, or Durable Objects.
• Direct-public deployment — when uploaded media is readable before the manifest gates it.
• Conformance — assertion catalogue covering the protocol surface.

Release check

bun --filter '@arsenstorm/olos' publish:check