**Lightspeed** is a production-ready, LiveView-style web framework for Gleam.
Build server-rendered, stateful, realtime interfaces in Gleam without splitting
core logic across a separate frontend framework.
Lightspeed is designed for teams that need strong runtime guarantees, typed
application contracts, and operational control on the BEAM.
Lightspeed uses Gleam's strengths:
- explicit types
- immutable state
- BEAM processes
- typed actor messages
- transport-independent protocols
- testable pure functions
- optional JavaScript target/client support
## Why Lightspeed
- server-owned session lifecycle with typed event handling
- deterministic patch protocol and transport contracts
- built-in parity coverage for forms, uploads, async, channels, and presence
- reproducible operator workflows with fixture-gated evidence
- release certification path with `make production-ready`
## Status
`1.0.0` parity GA is complete through M20.
Post-GA competitive hardening is complete through M60.
Production-readiness certification is enforced by `make production-ready`.
Historical `0.1.0-rc` references:
- public API subset: `specs/0007-public-api.md`
- migration notes: `docs/migration_0.1.0-rc.md`
- protocol freeze notes: `docs/protocol.md`
- release checklist: `docs/release_checklist_0.1.0-rc.md`
GA references:
- compatibility matrix: `docs/compatibility_matrix_1.0.0.md`
- deprecation policy: `docs/deprecation_policy.md`
- support policy: `docs/support_policy.md`
- upgrade guide: `docs/upgrade_0.1.0-rc_to_1.0.0.md`
- GA release checklist: `docs/release_checklist_1.0.0.md`
## Install
```sh
gleam add lightspeed
```
## Quick start
```gleam
import lightspeed
import lightspeed/component
pub fn index_markup() -> String {
let rendered = component.html("<h1>" <> lightspeed.banner() <> "</h1>")
component.to_html(rendered)
}
```
Generate local API docs with `make docs`, then open
`build/dev/docs/lightspeed/index.html`.
## Runtime model
A Lightspeed live view is a server-owned state machine:
1. The first request returns static HTML.
2. The browser connects over a live transport, normally WebSocket.
3. A per-session server process owns state.
4. Browser events are decoded into typed messages.
5. Application state is updated.
6. A render pass produces a new HTML tree or fragment.
7. Lightspeed sends a patch instruction to the client.
8. The client applies the patch and acknowledges it.
## Repository layout
```text
.
├── src/ # Gleam library modules
│ └── lightspeed/
│ ├── agent/ # typestate + ISA agents
│ ├── component.gleam # component contract
│ ├── component/ # helpers + stateful/template/story APIs
│ ├── diff.gleam # patch model
│ ├── event.gleam # typed event decoders
│ ├── form.gleam # form bindings
│ ├── framework/ # endpoint/controller/verified-routes layer
│ ├── ops/ # production hardening helpers
│ ├── channel.gleam # channel routing core
│ ├── presence.gleam # presence diff tracker
│ ├── protocol.gleam # wire frame model
│ ├── pubsub.gleam # pubsub fanout abstraction
│ ├── router.gleam # router integration layer
│ ├── pipeline.gleam # ETL pipeline lifecycle contracts
│ ├── pipeline/ # checkpoint + telemetry + quality + SLO ETL contracts
│ └── transport.gleam # transport abstraction
├── test/ # gleeunit tests
├── client/ # browser runtime + JS command layer
├── docs/ # design docs and developer docs
├── specs/ # normative specifications
├── rfcs/ # change proposals
├── adrs/ # architecture decision records
├── examples/ # example applications and API usage
├── Makefile
└── gleam.toml
```
## Core concepts
### Developer ergonomics (Phase 6)
Application-facing helpers are available in:
- `lightspeed/component/helpers`
- `lightspeed/router`
- `lightspeed/form`
- `lightspeed/event`
See `examples/crud/README.md` for an end-to-end typed flow combining route
matching, event decoding, form bindings, and command helpers.
### Production hardening (Phase 7)
Operational helper modules:
- `lightspeed/ops/supervision`
- `lightspeed/ops/telemetry`
- `lightspeed/ops/load_harness`
- `lightspeed/ops/quality_harness`
- `lightspeed/ops/performance_harness`
- `lightspeed/ops/channel_harness`
Deployment and security guidance:
- `docs/supervision_tree.md`
- `docs/security_review.md`
- `docs/deployment_guide.md`
- `docs/performance_report.md`
- `docs/channel_performance_report.md`
- `docs/operator_runbook.md`
- `docs/production_readiness_checklist.md`
### Realtime compatibility (Phase 14)
Channel-focused modules:
- `lightspeed/pubsub`
- `lightspeed/presence`
- `lightspeed/channel`
### Component/template compatibility (Phase 15)
Component-focused modules:
- `lightspeed/component/stateful`
- `lightspeed/component/template`
- `lightspeed/component/story`
Migration examples:
- `docs/component_migration_examples.md`
### Client JS compatibility (Phase 16)
Client runtime command surface:
- `LightspeedJS.addClass` / `removeClass` / `toggleClass`
- `LightspeedJS.setAttribute` / `removeAttribute`
- `LightspeedJS.show` / `hide` / `toggle` / `transition`
- `LightspeedJS.dispatch`
- `LightspeedJS.push` / `patch` / `navigate`
- deterministic `concat`/composition ordering
- patch-aware persistent command replay
Interop examples and notes:
- `docs/client_js_command_compat.md`
### LiveView-style test DSL compatibility (Phase 17)
Testing-focused module:
- `lightspeed/testing/liveview`
Migration examples:
- `docs/liveview_test_migration_examples.md`
### Generator tooling compatibility (Phase 25)
Generator modules:
- `lightspeed/tooling/generator`
- `lightspeed/ops/generator_harness`
M25 depth additions:
- production-ready `new` scaffolds with data-scope and migration defaults
- deeper `gen.live` / `gen.html` / `gen.json` / `gen.auth` integration-test scaffolds
- deterministic generator snapshot signatures and drift guards
Generator docs:
- `docs/generator_tooling.md`
- `docs/reports/generator_fixture_latest.md`
### Data/domain migration compatibility (Phase 19)
Data and migration modules:
- `lightspeed/data/repository`
- `lightspeed/data/migration`
- `lightspeed/ops/migration_harness`
Migration/operator docs:
- `docs/data_integration.md`
- `docs/migration_reference_small.md`
- `docs/migration_reference_medium.md`
- `docs/mixed_runtime_cookbook.md`
- `docs/operator_migration_playbook.md`
### Ecosystem integration compatibility (Phase 26)
Integration modules:
- `lightspeed/integration/data`
- `lightspeed/integration/jobs`
- `lightspeed/integration/mail`
- `lightspeed/integration/ops`
- `lightspeed/integration/stack`
- `lightspeed/ops/integration_harness`
M26 additions:
- first-class integration patterns for data, jobs, mail, and operator tooling
- deterministic reference stack setup/teardown signatures
- integration fixture drift report and CI gate
Integration docs:
- `docs/ecosystem_integration.md`
- `docs/integration_reference_stacks.md`
- `docs/operator_integration_runbook.md`
- `docs/reports/integration_fixture_latest.md`
### Durable cluster failover compatibility (Phase 27)
Failover modules:
- `lightspeed/cluster/durable_session`
- `lightspeed/ops/failover_harness`
M27 additions:
- durable session persistence contracts for snapshot/journal backends
- deterministic ownership-fencing rules for stale-owner and split-brain rejection
- deterministic failover certification harness across crash/restart/reconnect paths
- failover fixture drift report and CI gate
Failover docs:
- `docs/durable_cluster_runtime.md`
- `docs/failover_certification.md`
- `docs/reports/failover_fixture_latest.md`
### Large data + async backpressure compatibility (Phase 28)
M28 modules:
- `lightspeed/data_plane`
- `lightspeed/async/backpressure`
- `lightspeed/ops/large_data_harness`
M28 additions:
- high-volume list/grid/chart windowed-query contracts
- incremental keyed updates with full-root churn detection helpers
- async runtime queue/in-flight backpressure boundaries and recoverable cancellation/failure paths
- deterministic heavy-workload budgets plus fixture drift report and CI gate
M28 docs:
- `docs/large_data_runtime.md`
- `docs/reports/large_data_fixture_latest.md`
### Tenant isolation and policy runtime compatibility (Phase 29)
M29 modules:
- `lightspeed/tenant/policy`
- `lightspeed/ops/tenant_harness`
M29 additions:
- first-class tenant context propagation across runtime/data/telemetry surfaces
- deterministic row/action policy checks with explicit denial telemetry
- per-tenant budgets/quotas for events, sessions, and jobs
- noisy-neighbor containment and auditability fixtures with CI drift gate
M29 docs:
- `docs/tenant_policy_runtime.md`
- `docs/operator_tenant_playbook.md`
- `docs/reports/tenant_fixture_latest.md`
### Chaos/fuzz and SLO autopilot gate (Phase 30)
M30 modules:
- `lightspeed/ops/slo_autopilot`
- `lightspeed/ops/chaos_harness`
M30 additions:
- deterministic protocol/runtime fuzz corpus regression checks
- deterministic chaos fault-injection suite across transport/runtime/storage surfaces
- typed SLO burn-rate thresholds and mitigation-control runtime with auditable/rollbackable actions
- tracked M30 fixture drift report and CI gate
M30 docs:
- `docs/chaos_fuzz_slo_gate.md`
- `docs/operator_slo_autopilot_playbook.md`
- `docs/reports/chaos_fixture_latest.md`
### Integrated data pipeline core (Phase 31)
M31 modules:
- `lightspeed/pipeline`
- `lightspeed/pipeline/checkpoint`
- `lightspeed/pipeline/telemetry`
- `lightspeed/ops/pipeline_harness`
M31 additions:
- first-class source/transform/sink pipeline lifecycle contracts
- deterministic checkpoint/watermark/resume-point and sink idempotency-key contracts
- deterministic lag/throughput/retry/dead-letter telemetry contracts + metric projection
- deterministic success/partial-failure/replay/crash-resume/idempotency fixture signatures
- tracked M31 fixture drift report and CI gate
M31 docs:
- `docs/data_pipeline_core.md`
- `docs/operator_pipeline_playbook.md`
- `docs/reports/pipeline_fixture_latest.md`
### Connector and orchestration parity (Phase 32)
M32 modules:
- `lightspeed/pipeline/connector`
- `lightspeed/pipeline/orchestrator`
- `lightspeed/pipeline/operator`
- `lightspeed/ops/connector_harness`
M32 additions:
- connector abstractions for database/file/queue extraction and database/pubsub loading
- backpressure-aware orchestration boundaries integrating pipeline lifecycle and queue/in-flight controls
- retry/dead-letter/reprocess-window policy contracts for connector failures
- operator pause/resume/drain/replay control contracts with deterministic audit signatures
- tracked M32 fixture drift report and CI gate
M32 docs:
- `docs/pipeline_connector_orchestration.md`
- `docs/operator_connector_playbook.md`
- `docs/reports/connector_fixture_latest.md`
### ETL reliability and SLO gate (Phase 33)
M33 modules:
- `lightspeed/pipeline/quality`
- `lightspeed/pipeline/slo`
- `lightspeed/ops/etl_reliability_harness`
M33 additions:
- deterministic outage, poison-message quarantine/replay, and idempotency reliability fixtures
- schema-evolution compatibility and payload-quality boundary contracts
- versioned ETL SLO budgets for lag, throughput, retry rate, and replay recovery time
- tracked fixture + budget reports with CI drift gates
M33 docs:
- `docs/etl_reliability_slo_gate.md`
- `docs/operator_etl_playbook.md`
- `docs/reports/etl_fixture_latest.md`
- `docs/reports/etl_budget_latest.md`
### Production load benchmark suite (Phase 34)
M34 module:
- `lightspeed/ops/load_harness`
M34 additions:
- deterministic production-load fixture matrix across baseline, slow-ack, and clean-ack profiles
- stable fixture report and snapshot signatures for regression auditing
- tracked M34 load fixture report with CI drift gate
M34 docs:
- `docs/load_benchmark_suite.md`
- `docs/reports/load_fixture_latest.md`
### Runtime hot-path optimization suite (Phase 35)
M35 module:
- `lightspeed/ops/hot_path_harness`
M35 additions:
- deterministic hot-path matrix tied to M34-shaped load traces
- baseline vs optimized p95/throughput/allocation signatures per scenario
- tracked M35 hot-path fixture report with CI drift gate
M35 docs:
- `docs/hot_path_optimization_suite.md`
- `docs/reports/hot_path_fixture_latest.md`
### Render churn reduction for high-frequency views (Phase 36)
M36 modules:
- `lightspeed/diff`
- `lightspeed/stream`
- `lightspeed/ops/render_churn_harness`
M36 additions:
- keyed reorder patch operation for deterministic dense-tree order correction
- reduced stream reorder churn via keyed diff + reorder plans
- tracked M36 render-churn fixture report with CI drift gate
M36 docs:
- `docs/render_churn_reduction.md`
- `docs/reports/render_churn_fixture_latest.md`
### Durable store contention profiling for clusters (Phase 37)
M37 modules:
- `lightspeed/cluster/durable_session`
- `lightspeed/ops/contention_harness`
M37 additions:
- deterministic contention profiling for ownership fencing, lease renewals, and
takeover queue/retry pressure
- deterministic checkpoint/replay-window profiles across durable backends
- tunable contention budgets with tracked M37 fixture report and CI drift gate
M37 docs:
- `docs/contention_profiling_clusters.md`
- `docs/reports/contention_fixture_latest.md`
### App platform parity foundations (Phase 38)
M38 modules:
- `lightspeed/platform/foundation`
- `lightspeed/ops/app_platform_harness`
M38 additions:
- production-shaped app-platform seam contracts for auth/admin/policy/billing
with explicit override points
- deterministic reference product-composition profiles for multi-surface app
workflows
- deterministic M38 conformance harness and tracked fixture report CI drift gate
M38 docs:
- `docs/app_platform_parity_foundations.md`
- `docs/reports/app_platform_fixture_latest.md`
### HTML/template ergonomics and productivity parity (Phase 39)
M39 modules:
- `lightspeed/component/template_ergonomics`
- `lightspeed/ops/template_ergonomics_harness`
M39 additions:
- ergonomic typed-assign/slot/attr authoring helpers for routine template paths
- deterministic migration-hint diagnostics for common authoring failures
- reduced routine composition boilerplate via automatic slot passthrough and
slot defaults
- deterministic M39 fixture report and CI drift gate
M39 docs:
- `docs/template_ergonomics_parity.md`
- `docs/reports/template_ergonomics_fixture_latest.md`
### Tenant isolation and policy runtime expansion (Phase 52)
M52 modules:
- `lightspeed/tenant/policy`
- `lightspeed/ops/tenant_expansion_harness`
M52 additions:
- cross-surface tenant-policy controls across runtime/data/pipeline workflows
- expanded per-tenant pipeline and mitigation budgets for noisy-neighbor containment
- deterministic decision telemetry for allow/deny/mitigated policy outcomes
- deterministic M52 fixture report and CI drift gate
M52 docs:
- `docs/tenant_policy_runtime_expansion.md`
- `docs/tenant_policy_containment_matrix.md`
- `docs/operator_tenant_policy_expansion_playbook.md`
- `docs/reports/tenant_expansion_fixture_latest.md`
### Chaos and fault-injection verification harness expansion (Phase 53)
M53 modules:
- `lightspeed/ops/chaos_expansion_harness`
- `lightspeed/ops/chaos_harness`
- `lightspeed/ops/replay_diagnostics`
M53 additions:
- deterministic compound chaos verification across transport/runtime/storage/data surfaces
- deterministic incident-pack replay certification for runtime/session/pipeline recovery paths
- deterministic autopilot and operator mitigation-flow integration evidence
- versioned failure taxonomy/remediation mappings with deterministic fixture signatures
- deterministic M53 fixture report and CI drift gate
M53 docs:
- `docs/chaos_fault_injection_verification_expansion.md`
- `docs/chaos_failure_taxonomy_and_remediation.md`
- `docs/operator_chaos_verification_playbook.md`
- `docs/reports/chaos_expansion_fixture_latest.md`
### Operational autopilot and SLO-aware controls expansion (Phase 54)
M54 modules:
- `lightspeed/ops/operational_autopilot`
- `lightspeed/ops/operational_autopilot_harness`
M54 additions:
- cross-surface SLO-aware control loops for runtime, transport, tenant, and ETL surfaces
- policy-bounded automated mitigations with explicit override and blocked-policy semantics
- deterministic incident correlation evidence for triage and recovery timing
- deterministic M54 fixture report and CI drift gate
M54 docs:
- `docs/operational_autopilot_slo_controls_expansion.md`
- `docs/autopilot_policy_override_matrix.md`
- `docs/operator_operational_autopilot_playbook.md`
- `docs/reports/operational_autopilot_fixture_latest.md`
### First-class nested LiveView lifecycle primitives (Phase 55)
M55 modules:
- `lightspeed/component/nested_lifecycle`
- `lightspeed/ops/nested_lifecycle_harness`
M55 additions:
- first-class parent/child lifecycle contracts with stable child identity
- mount/update/suspend/resume/terminate/fail behavior for nested trees
- scoped event routing and child boundary patch targeting
- deterministic subtree-failure isolation evidence and CI drift gate
M55 docs:
- `docs/first_class_nested_liveview_lifecycle_primitives.md`
- `docs/nested_liveview_migration_guide.md`
- `docs/operator_nested_liveview_playbook.md`
- `docs/reports/nested_lifecycle_fixture_latest.md`
### Transport compatibility and progressive enhancement model expansion (Phase 56)
M56 modules:
- `lightspeed/transport/progressive_enhancement`
- `lightspeed/ops/transport_expansion_harness`
M56 additions:
- explicit transport negotiation policies with downgrade/upgrade transitions
- proxy/protocol guidance checks with deterministic acceptance/warning signatures
- degraded workflow parity certification for navigation/forms/mutations
- deterministic reconnect parity certification across websocket/SSE/long-polling profiles
- deterministic M56 fixture report and CI drift gate
M56 docs:
- `docs/transport_compatibility_progressive_enhancement_expansion.md`
- `docs/transport_mode_certification_matrix.md`
- `docs/operator_transport_compatibility_playbook.md`
- `docs/reports/transport_expansion_fixture_latest.md`
### ORM/data ergonomics parity profile (Phase 57)
M57 modules:
- `lightspeed/data_ergonomics`
- `lightspeed/ops/data_ergonomics_harness`
M57 additions:
- typed CRUD/dashboard ergonomics helpers over changeset contracts
- nested changeset validation propagation with deterministic error signatures
- transaction/unit-of-work contracts with explicit optimistic-concurrency checks
- deterministic query diagnostics for N+1, slow query, and trace correlation
- deterministic M57 fixture report and CI drift gate
M57 docs:
- `docs/orm_data_ergonomics_parity_profile.md`
- `docs/query_diagnostics_ergonomics_matrix.md`
- `docs/operator_data_ergonomics_playbook.md`
- `docs/reports/data_ergonomics_fixture_latest.md`
### Turnkey app platform defaults and presets (Phase 58)
M58 modules:
- `lightspeed/platform/turnkey_presets`
- `lightspeed/ops/turnkey_presets_harness`
M58 additions:
- production-shaped starter presets for auth/admin/billing/policy/email/queue domains
- one-command scaffold semantics for secure baseline presets
- explicit override seams with external ownership and no framework-internal edits
- deterministic critical-flow certification scenarios for platform baseline workflows
- deterministic M58 fixture report and CI drift gate
M58 docs:
- `docs/turnkey_app_platform_defaults_presets.md`
- `docs/preset_flow_certification_matrix.md`
- `docs/operator_turnkey_preset_playbook.md`
- `docs/reports/turnkey_presets_fixture_latest.md`
### Developer tooling polish and productivity suite (Phase 59)
M59 modules:
- `lightspeed/tooling/developer_productivity`
- `lightspeed/ops/developer_tooling_harness`
M59 additions:
- richer typed runtime diagnostics surfaces for session/event/diff/transport workflows
- actionable profiling surfaces for latency/allocation/render hotspots
- deterministic generator/refactor quality-gate and patch-churn-reduction contracts
- deterministic editor diagnostics and jump-to-symbol navigation metadata contracts
- deterministic M59 fixture report and CI drift gate
M59 docs:
- `docs/developer_tooling_polish_productivity_suite.md`
- `docs/tooling_diagnostics_navigation_matrix.md`
- `docs/operator_developer_tooling_playbook.md`
- `docs/reports/developer_tooling_fixture_latest.md`
### Integrated data pipelines and ETL runtime operations surface (Phase 60)
M60 modules:
- `lightspeed/pipeline/operations_surface`
- `lightspeed/ops/pipeline_operations_surface_harness`
M60 additions:
- integrated tenant-aware run/replay/control workflow surfaces for ETL runtime operations
- resumable checkpoint lineage and freshness metadata contracts for operator-facing evidence
- heavy-data source/sink conformance evidence across adapter profiles with deterministic benchmark and budget signatures
- deterministic M60 fixture report and CI drift gate
M60 docs:
- `docs/integrated_data_pipelines_etl_runtime_operations_surface.md`
- `docs/pipeline_operations_conformance_matrix.md`
- `docs/operator_pipeline_operations_surface_playbook.md`
- `docs/reports/pipeline_operations_surface_fixture_latest.md`
### Parity GA policy (Phase 20)
GA policy modules:
- `lightspeed/release/policy`
- `lightspeed/ops/ga_harness`
### Verified routes hard parity (Phase 22)
Verified routes modules:
- `lightspeed/framework/verified_routes`
- `lightspeed/ops/verified_routes_harness`
Migration guide:
- `docs/verified_routes_migration.md`
### Template compiler parity (Phase 23)
Template compiler modules:
- `lightspeed/component/template_compiler`
- `lightspeed/ops/template_harness`
Migration guide:
- `docs/template_compiler_migration.md`
### Transport matrix parity (Phase 24)
Transport matrix modules:
- `lightspeed/transport/matrix`
- `lightspeed/ops/transport_matrix_harness`
Compatibility/migration guide:
- `docs/transport_matrix_compat.md`
### Live component
A component is modeled as pure update/render logic plus explicit commands.
```gleam
pub type Component(model, msg) {
Component(
init: fn() -> model,
update: fn(model, msg) -> #(model, List(Command(msg))),
render: fn(model) -> Rendered,
)
}
```
### Typestate agent
The connection lifecycle is represented with phantom types. Invalid lifecycle transitions should fail at compile time.
```gleam
let agent = typestate.new("session-1")
let agent = typestate.handshake(agent)
let agent = typestate.mount(agent)
let agent = typestate.go_live(agent)
```
A function that requires `Agent(Live)` cannot receive `Agent(Disconnected)`.
### Orthogonal ISA
The Lightspeed ISA is a small instruction set that describes runtime effects independently of transport, HTTP server, renderer, or browser implementation.
Examples:
- `Mount`
- `Render`
- `Patch`
- `PushEvent`
- `Navigate`
- `Subscribe`
- `Unsubscribe`
- `Shutdown`
The same ISA can be interpreted by:
- a real BEAM actor
- a deterministic test runner
- a tracing tool
- a browser protocol encoder
- a future distributed runtime
## Local development
Prerequisites:
- Gleam
- Erlang/OTP
- Make
```sh
make setup
make ci
```
Useful targets:
```sh
make fmt
make check
make test
make test-client
make docs
make channel-report
make integration-fixture
make failover-fixture
make large-data-fixture
make tenant-fixture
make chaos-fixture
make chaos-expansion-fixture
make operational-autopilot-fixture
make nested-lifecycle-fixture
make transport-expansion-fixture
make data-ergonomics-fixture
make pipeline-fixture
make connector-fixture
make etl-fixture
make etl-budget
make hot-path-fixture
make render-churn-fixture
make contention-fixture
make app-platform-fixture
make template-ergonomics-fixture
make operations-kit-fixture
make adapter-sdk-fixture
make replay-diagnostics-fixture
make protocol-contract-fixture
make ai-workflow-fixture
```
## Ecosystem interoperability
Lightspeed integrates with existing Gleam ecosystem tools. Wisp/Mist can serve
HTTP and WebSocket infrastructure, Lustre can inform rendering strategy, and
`gleam_otp` provides the actor substrate.
Lightspeed's focus is the LiveView-style runtime contract: typed events,
stateful sessions, lifecycle safety, deterministic patch delivery, and
operational certification.
## Versioning
As of `1.0.0`, the public API and protocol are stable under semantic versioning.
Breaking changes require a major version and documented migration notes.
Planned compatibility boundaries:
- all code changes require both an RFC and an ADR.
- `lightspeed/protocol` changes require RFC migration notes.
- `lightspeed/agent/isa` changes require RFC migration notes.
- public module removals must document consequences in the ADR.
## License
Lightspeed is distributed under The Unlicense. See `LICENSE.md`.
