README
¶
Tessera
Tessera is a protocol for typed, schema-described records and optional content storage. This repository contains the specifications, portable test vectors, an importable Go conformance suite and a Go reference server with SQLite and PostgreSQL engines. Applications define their own vocabulary and workflows; Tessera stores their data without interpreting its meaning.
Status: v0.1.0-rc.4 is a release candidate. Final release acceptance is pending;
see the app and server acceptance checklist.
A passing backend test suite is not independent client acceptance or a conformance certificate.
Quick start
For a local experiment, install Go 1.27.0 and a C compiler, enable CGO, then run:
make dev
The synthetic development server listens at http://127.0.0.1:8080 and keeps its
SQLite database and private bearer-token file under .tessera-dev/. The token is
written to .tessera-dev/token, never printed. Use synthetic data only.
Run make dev-content to include filesystem attachments. See the
development guide for connecting and resetting.
For other uses:
| I want to… | Start here |
|---|---|
| Understand the data model and HTTP API | Protocol overview |
| Run a private HTTPS server | Self-hosting, then deployment examples |
| Use or embed the Go packages | Consuming Tessera |
| Check supported features and limitations | Feature matrix |
| Work on the project | Contributing |
| Find a reference or decision | Documentation index |
How it works
A server holds datasets with their own identities, schemas and access grants. Clients read records through bounded queries and submit ordered, atomic transactions. Durable engines provide idempotent write recovery, pagination, retirement and encrypted backup export. Optional content storage keeps attachment bytes outside the record API.
The standalone server supplies OAuth/PKCE, accounts, invitations and administration. SQLite serves many datasets in one process; PostgreSQL supports multiple processes, subject to the identity and backup deployment constraints. Live-storage encryption is supplied by the operator's filesystem or volume.
The record protocol and content protocol define correctness and version independently. The reference server does not define the contract. Implementers can use the conformance suites against their own HTTP server and share the frozen, append-only vectors.
Development
make check
This runs formatting, vet and race-enabled tests. PostgreSQL tests can skip when no disposable databases are configured; use the verification instructions before claiming coverage of both engines. Windows contributors use the WSL workflow. Agent-specific setup and change workflows start in AGENTS.md.
Licence
Apache-2.0, including its patent grant.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tesserad
command
tesserad composes the synthetic development or HTTPS self-hosted deployment.
|
tesserad composes the synthetic development or HTTPS self-hosted deployment. |
|
db
|
|
|
migrations
Package migrations embeds hand-written SQLite schema migrations.
|
Package migrations embeds hand-written SQLite schema migrations. |
|
internal
|
|
|
acquisition
Package acquisition owns bounded reference-server backup publication.
|
Package acquisition owns bounded reference-server backup publication. |
|
admin
Package admin serves the standalone administration surface: server-rendered HTML over embedded assets, with no client vocabulary, workflow or approval flow in it.
|
Package admin serves the standalone administration surface: server-rendered HTML over embedded assets, with no client vocabulary, workflow or approval flow in it. |
|
dbtest
Package dbtest answers one question for every test that needs a PostgreSQL database: is there one, and is going without allowed here?
|
Package dbtest answers one question for every test that needs a PostgreSQL database: is there one, and is going without allowed here? |
|
devfaults
Package devfaults injects synthetic transport faults.
|
Package devfaults injects synthetic transport faults. |
|
devserver
Package devserver composes the synthetic, loopback-only development server.
|
Package devserver composes the synthetic, loopback-only development server. |
|
identity
Package identity implements the standalone authorization server.
|
Package identity implements the standalone authorization server. |
|
recordstate
Package recordstate evaluates bounded Tessera datasets for the memory and SQLite engines.
|
Package recordstate evaluates bounded Tessera datasets for the memory and SQLite engines. |
|
release
Package release reports what this binary was actually built from.
|
Package release reports what this binary was actually built from. |
|
sqlengine
Package sqlengine shares bounded evaluation, recovery and content authority across the SQLite and PostgreSQL public engine entry points.
|
Package sqlengine shares bounded evaluation, recovery and content authority across the SQLite and PostgreSQL public engine entry points. |
|
standalone
Package standalone composes the self-hosted server; its HTTP surface contains no product-specific schemas or workflow.
|
Package standalone composes the self-hosted server; its HTTP surface contains no product-specific schemas or workflow. |
|
pkg
|
|
|
conformance
Package conformance exercises the implemented Tessera core subset over HTTP.
|
Package conformance exercises the implemented Tessera core subset over HTTP. |
|
protocol
Package protocol implements the Tessera protocol's value and metadata contracts.
|
Package protocol implements the Tessera protocol's value and metadata contracts. |
|
server
Package server exposes the implemented Tessera HTTP subset for embedding.
|
Package server exposes the implemented Tessera HTTP subset for embedding. |
|
store
Package store defines Tessera's authorized transaction boundary.
|
Package store defines Tessera's authorized transaction boundary. |
|
store/memory
Package memory provides a synthetic, non-durable evaluator holding exactly one dataset.
|
Package memory provides a synthetic, non-durable evaluator holding exactly one dataset. |
|
store/postgres
Package postgres provides durable storage in a dedicated PostgreSQL database.
|
Package postgres provides durable storage in a dedicated PostgreSQL database. |
|
store/sqlite
Package sqlite provides durable SQLite storage.
|
Package sqlite provides durable SQLite storage. |