Projections API

The causet-projection-worker is a Kafka consumer — it has no inbound REST API. It reads from causet.projection-events.v1, evaluates projection handlers against each event, and writes rows to PostgreSQL projection tables.

Projection state is observable via health endpoints, metrics, and the control plane.

Projection Worker

The projection worker has no public REST API. All external interaction is through:

• Health endpoint — service liveness and readiness
• Metrics — Prometheus metrics for lag, failure rate, throughput
• Control plane — web UI and API for failure records and release management
• Direct DB query — projection tables are plain PostgreSQL

Health Check

GET /actuator/health
Host: causet-projection-worker:8083

Response:

{
  "status": "UP",
  "components": {
    "kafka": { "status": "UP" },
    "db":    { "status": "UP" }
  }
}

The worker reports DOWN if Kafka or the projections database is unreachable.

Release Deployment and DDL

When a new release is deployed to a fork, causet-saas-cloud triggers IR-driven DDL against the tenant schema. The DDL is derived from causet.projections.json.

Operations performed:

• Create tenant schema if it does not exist: {platformId}_{applicationId}_{forkId}
• CREATE TABLE IF NOT EXISTS for each projection table
• ADD COLUMN IF NOT EXISTS for new fields
• CREATE INDEX IF NOT EXISTS for each index defined in the projection

DDL is additive only. Removing a field from the DSL does not drop the column from the database. Plan additive schema changes and backfill via projection replay when needed.

Tenant schema naming:

{platformId}_{applicationId}_{forkId}

Example: my_platform_concert_app_main

Projection Failure Records

When the projection worker fails to process an event after exhausting its retry policy, it writes a failure record and routes the message to the DLQ (causet.projection-dlq.v1).

Failure record fields:

Querying Failure Records Directly

Failure records are stored in the projections database. Query them directly:

SELECT id, projection_name, event_type, entity_id, error_message, failed_at
FROM projection_failures
WHERE resolved = false
ORDER BY failed_at DESC;

Proposed: A REST API for projection failure records is on the roadmap. Currently accessible via direct database query or the control plane UI.

Control Plane UI

The control plane (causet-cloud-control-plane, port 3000) displays projection failures in the application dashboard under Projections → Failures.

Projection Rebuild (Replay)

To rebuild a projection from the beginning, reset the Kafka consumer group offset for the projection worker.

Using the Kafka CLI:

kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group causet-projection-worker \
  --reset-offsets \
  --to-earliest \
  --topic causet.projection-events.v1 \
  --execute

Before resetting, truncate the projection table to avoid duplicate key violations:

TRUNCATE TABLE {tenant_schema}.{projection_table};
DELETE FROM projection_checkpoints WHERE projection_name = '{projection_name}';

Warning: Offset reset is destructive. The worker will reprocess all events from the beginning. Do not replay projections that have external side effects (webhooks, billing, notifications).

Monitor recovery via Kafka consumer lag metrics. Replay is complete when consumer lag reaches 0.

Note: Rebuilding a projection from ledger history is available via the control plane and SDK — contact support for bulk replay operations on Causet Cloud.

Projection Checkpoints

The worker stores per-projection checkpoints in a projection_checkpoints table in the projections database. Checkpoints track the last successfully processed Kafka offset per projection.

SELECT projection_name, last_offset, last_processed_at
FROM projection_checkpoints
ORDER BY last_processed_at DESC;

Checkpoints enable the worker to resume from the correct position after a restart without reprocessing already-handled events.

Kafka Topics

Metrics

The projection worker exposes Prometheus metrics at /actuator/prometheus.

Key metrics:

Configure alerts on causet_projection_lag_seconds > 30 and causet_dlq_messages_total increasing.