cloudlysis/projection/docs/scaling.md

Scaling & Provisioning

Consumer Modes

The projection supports two JetStream consumption modes (configured via PROJECTION_CONSUMER_MODE):

• single: one durable consumer per projection process. Each message is processed once and the projection updates all view_types defined in the manifest for that message.
• per_view: one durable consumer per view_type. Each consumer processes all events, but only updates its own view_type (checkpoint isolation and independent scaling).

In per_view mode, durable names are derived as:

{PROJECTION_DURABLE_NAME}_{view_type} (with non [A-Za-z0-9_-] replaced by _).

Replica Scaling

To scale replicas, run multiple instances with the same durable name(s):

• single mode: all replicas share one durable consumer and work-steal messages from that consumer.
• per_view mode: all replicas share a durable consumer per view_type.

Sharding

JetStream subject filtering does not support “hash/range shard by aggregate_id” on the consumer side.

If strict per-entity ordering is required across replicas, sharding must be encoded in the published subjects (for example shard.<n>.tenant.<id>.aggregate.<type>.<id>), and each shard must run with a matching PROJECTION_SUBJECT_FILTERS value.

Without subject-based sharding, multiple replicas can process events for the same view_id concurrently, which can break projections that depend on ordered read-modify-write updates.