Contrail #

Pre-alpha. Expect breaking changes.

Contrail turns public AT Protocol records into a queryable AppView.

It provides:

• historical backfill from relays and PDSes;
• current updates from Jetstream;
• D1, SQLite, and PostgreSQL storage;
• getRecord and listRecords HTTP endpoints;
• filters, sorting, search, and pagination;
• custom queries;
• relationship counts and hydration; and
• profile and label hydration.

Cloudflare Workers with D1 is the primary deployment target. Node.js with SQLite or PostgreSQL is also supported.

Install #

pnpm add @atmo-dev/contrail

Minimal Worker #

// src/contrail.config.ts
import type { ContrailConfig } from "@atmo-dev/contrail";

export const config: ContrailConfig = {
  namespace: "com.example",
  collections: {
    event: {
      collection: "community.lexicon.calendar.event",
      queryable: {
        mode: {},
        startsAt: { type: "range" },
      },
      searchable: ["name", "description"],
    },
  },
};

// src/worker.ts
import { createWorker } from "@atmo-dev/contrail/worker";
import { config } from "./contrail.config";

export default createWorker(config);

Add a D1 binding and one-minute cron to wrangler.jsonc:

{
  "main": "src/worker.ts",
  "d1_databases": [
    { "binding": "DB", "database_name": "contrail", "database_id": "..." }
  ],
  "triggers": { "crons": ["*/1 * * * *"] }
}

Then deploy and backfill:

npx wrangler d1 create contrail
pnpm wrangler deploy
pnpm contrail backfill --remote

Query the resulting AppView:

GET /xrpc/com.example.event.listRecords?startsAtMin=2026-01-01&limit=10

For ordinary Lexicon parsing, validation, pulling, and TypeScript generation, use Atcute directly. Contrail no longer ships a separate Lexicon toolchain.

Other databases #

import { createSqliteDatabase } from "@atmo-dev/contrail/sqlite";
import { createPostgresDatabase } from "@atmo-dev/contrail/postgres";

See Indexing for adapter setup and Querying for the query and hydration model.

Documentation #

• Indexing
• Querying
• Feeds
• Labels
• SvelteKit + Cloudflare

Repository layout #

There is one published package and one implementation:

packages/contrail/   @atmo-dev/contrail

The previous AppView, base, community, authority, record-host, sync, and Lexicon packages have been removed.

See development.md for repository commands.