fscl-messaging

Shared messaging and outbox contract crate for FSCL services.

It contains:

• EventEnvelope: canonical wire payload and outbox payload
• OutboxRecord: persisted outbox state around an envelope
• schema: embedded outbox SQL and shared schema constants

Dependencies

			 +------------------+
			 |  fscl-messaging  |
			 +---------+--------+
					 ^
					 |
	   +-----------------+-----------------+
	   |                                   |
	   |                                   |
   +----+-----+                       +-----+----------------+
   | fscl-core|                       | fscl-outbox-publisher|
   +----------+                       +-----------------------+
	   ^
	   |
   +----+----------------+
   | view-specific services|
   +----------------------+

This crate is the shared contract layer. It is intentionally below the service crates.

Split

schema.rs / sql/outbox.sql  -> code-level outbox contract
envelope.rs                 -> wire payload contract
outbox.rs                   -> persisted outbox state contract
env / ConfigMap / Secret    -> runtime values outside this crate

Config

fscl-messaging does not read env vars.

It centralizes code-level contract values only:

• OUTBOX_TABLE: shared outbox table name
• OUTBOX_NOTIFY_CHANNEL: shared PostgreSQL notify channel name
• OUTBOX_SCHEMA_VERSION: schema version marker
• OUTBOX_SCHEMA_SQL: embedded SQL for the shared outbox schema
• ensure_outbox_schema: apply the embedded outbox SQL through a sqlx Postgres pool

ensure_outbox_schema serializes concurrent installers with a PostgreSQL advisory transaction lock, so multiple services can call it during startup without racing each other through the DDL.

Example:

use fscl_messaging::ensure_outbox_schema;
use sqlx::PgPool;

async fn install_outbox(pool: &PgPool) -> Result<(), sqlx::Error> {
    ensure_outbox_schema(pool).await
}

Meaning of the main types:

• EventEnvelope: the canonical event payload written to outbox and published on the wire
• OutboxRecord: the envelope plus publisher state such as published_at, attempts, and last_error

Dev Setup

cd fscl-messaging
cargo test

No .env file is required for this crate.

K8s Setup

Scaffold only: fscl-messaging is not deployed directly.

Its contracts are reflected indirectly in the Kubernetes manifests under fscl/doc/rust/fscl-k8s:

• the outbox schema must be applied by the database-owning service
• the notify channel stays fixed by code contract
• runtime values such as NATS_URL and subject prefix are injected by ConfigMaps and Secrets