Server & Durability

Every LaserData deployment runs Apache Iggy, a persistent message streaming server written in Rust. Iggy uses a thread-per-core architecture with io_uring.

Paid deployments, BYOC, and On-Premise use VSR (Viewstamped Replication Revisited) for consensus and replication. Shared-host Free deployments run a single node.

This page explains write completion, topic durability, and server configuration. Durability defines what must survive after a successful write. You choose retention, segment size, and durability when you create a topic. The platform manages the server configuration.

Understand the Version Badges

A version ending in -ld identifies a LaserData build of the Iggy fork. The fork adds the managed AGDX extensions used by LaserData while retaining standard Iggy streaming behavior. Its artifact version identifies the deployed binary, and release notes identify the upstream revision it includes.

Iggy Server, Connectors, and the client SDKs have separate version numbers. An older badge in a screenshot does not identify the current release. Do not assume that matching numbers across those components are required, or that an SDK supports every server change because a basic connection succeeds.

Replication and Availability

A cluster commits an operation when the required quorum accepts it. A quorum is the minimum required group of replicas. In a three-node cluster, both replication and view changes require two replicas. The cluster can keep serving after one replica fails and restore that replica from its peers when it returns.

Single AZ places all three replicas in one availability zone. Enterprise also supports Multi AZ across three zones, so one zone failing does not remove the quorum. See Tiers & Storage.

Warden waits for a healthy roster of all nodes before it issues credentials. A node can start before it finishes recovery, partition repair, or replay of managed state. Read node readiness and replication metrics before sending production traffic. A heartbeat shows that the process is alive, not that it caught up.

Clients use advertised addresses and follow leadership changes automatically. Warden configures those addresses and the roster. You do not edit them.

TCP-TLS and secure WebSocket connections use the configured server shards for handshakes and encrypted traffic. A shard is a unit of work assigned to a core. Encrypted connections can therefore use the node's allocated cores.

Heartbeat freshness follows the current view, a numbered leadership period. A new primary can start with a lower heartbeat counter. Replayed heartbeats from the same view cannot keep a failed primary marked live.

Topic Durability

Message durability and consumer-offset durability are independent. A consumer offset records a reader's position in a partition. Select both policies when you create a topic.

Both policies accept replicated or persisted. Both write data to disk. They differ in what must finish before the server reports success.

With replicated, acknowledged messages can remain in a replica's in-memory journal until a flush trigger fires. Replication protects those messages while enough replicas retain their copies. A failure that destroys the memory copies on a quorum, such as shared power loss, can lose acknowledged writes. A Free deployment has one node, so its quorum of one provides no second copy.

With persisted, acknowledged operations are recoverable while the required stable-storage copies remain intact and storage honors synchronization. Clustered partitions use a bounded on-disk prepare log during replication. Messages do not need to reach segment files before completion. This policy does not protect against retention, deletion, or loss of every durable copy.

The two policies default independently to replicated. Selecting persisted for messages does not change the consumer-offset policy. To persist both messages and explicit offset changes, create the topic with both policies:

iggy topic create my-stream my-topic 1 none \
  --durability persisted \
  --consumer-offset-durability persisted

These policies are create-only. UpdateTopic cannot change them on existing topics. The server rejects the removed enforce_fsync topic field.

Persisted completion adds synchronization. Its latency and throughput depend on storage, batching, and concurrency. Local NVMe, available from Performance, offers the lowest read and write latency for persisted topics.

Acknowledgements and Offset Commits

Wait for the server to complete a write. Adding a message to a producer's local queue does not prove server completion.

An awaited HTTP write returns 201 Created with an Iggy-Durability header that names the topic policy. With ?ack=none, HTTP returns 202 Accepted and Iggy-Durability: none after dispatch, without waiting for commit or persistence. The value ack=replicated selects the awaited path, including for persisted topics. It does not weaken their policy.

Poll auto-commit runs asynchronously, without waiting for offset completion. A successful poll does not prove that its offset committed or became durable, even with persisted consumer offsets. If processing needs an explicit completion boundary, process the message, then store the offset and wait for success. Delivery can repeat after failover, so downstream effects must tolerate repeated messages.

A timed-out poll does not prove rejection. With auto-commit, the server can advance the offset before the response reaches the client. Retrying with next can then skip messages from that missing response.

Keep a checkpoint for each partition, one past the last message processed in order. After a missing response, poll from that explicit offset. Advance the checkpoint only after processing the returned messages. Use each message's offset rather than the partition's current offset.

Backpressure

Each partition limits the produce and offset operations that wait for commit. If its prepare and request queues fill, the server returns TransientNotAccepted. This response proves that the request was not admitted, so it permits a retry without a duplicate write. The Rust SDK retries automatically.

For HTTP produce and offset writes, the server retries this response against other cluster nodes until the retry deadline. It then returns the error if no attempt succeeds. TransientNotCommitted means that the operation can still commit. The server does not retry that response for you.

Topic Storage Options

Flush thresholds control batching and I/O frequency. Lower thresholds do not give replicated the guarantees of persisted. Persisted completion can flush below ordinary thresholds, so messages_required_to_save does not need to be one.

Retention removes sealed segments and leaves the active segment intact. Every partition keeps at least one segment on disk. Storage capacity and segment size therefore bound partition counts. The deployment preview returns those bounds.

After creation, only compression_algorithm, message_expiry, and max_topic_size can change. Use GET /options/topic or iggy options topic to list supported topic configuration and defaults for the running version.

Server Configuration

The server merges one TOML file over defaults embedded in the binary. Each key supports an IGGY_ environment override. Main sections include node, cluster, sharding, partition, metadata, http, tcp, quic, websocket, telemetry, logging, encryption, and data_maintenance. Sections belong at the file's top level. Unknown keys and the removed system table prevent startup.

Warden generates and applies this configuration on LaserData Cloud. You change permitted values through the deployment's versioned configuration. Its schema lists types, defaults, and rules. The platform owns listener addresses, TLS material, the cluster roster, shard placement, and secrets.

These managed fields affect operation:

• partition.wal_bytes_max limits the on-disk prepare log for a persisted partition. Its default is 256 MiB. Capacity pressure causes checkpointing and backpressure without weakening durability.
• partition.wal_group_commit_delay_micros permits a wait for more prepares before one synchronization step applies to the group. The default is 0, with a maximum of 10,000 microseconds. It trades acknowledgement latency for fewer device writes without changing durability. An idle partition does not wait.
• message_bus.reconnect_period defaults to 1 s and also limits each outbound TCP dial between replicas. An unanswered dial cannot hold the reconnect sweep indefinitely. Stored overrides remain effective after a binary upgrade, including the connection deadline.
• The HTTP metrics endpoint requires authentication. Warden reads it for platform telemetry.

On-Premise Notes

On-Premise uses the same binaries and Warden configuration. Review host service limits, memory policy, CPU placement, and shutdown grace periods. If the grace period expires and the process is killed, shutdown did not finish. Only a completed graceful shutdown forces a final flush of committed replicated messages.

Upgrades are forward-compatible. The current server writes an extended on-disk superblock, a record of durable server state. To return a node to an older release, wipe its data directory and let it recover from peers. The platform manages server upgrades for you.

Coming Soon

Tiered storage and a Kafka gateway are planned and are not available. Tiered storage will move sealed segments to object storage such as S3 for retention beyond disk capacity. A Kafka gateway will let applications connect with their existing Kafka SDK or client.