Directory spool

Schemes: spool://, dir-spool://, dirspool://

Query parameters recognised as config fields for this connector. Unrecognised parameters are not forwarded as driver options, so any other ?key=value pair is rejected rather than silently ignored.

Name	Type	Required	Default	Description
`atomic`	boolean	no	`true`	(Sink only) Write to a `.tmp` name and rename into place, so a reader never sees a partial chunk. Defaults to true; turning it off trades that guarantee for one less rename per chunk.
`claim`	`exclusive` \| `warn` \| `off`	no	`exclusive`	How this endpoint claims its side of the spool against a second instance in the same role. Defaults to `exclusive`. See [`SpoolClaim`].
`consumer_file`	string	no	`CONSUMER`	Name of the file holding the consumer lock, which keeps a second draining consumer out. Defaults to `CONSUMER`. Same rules as `producer_file`.
`done_file`	string	no	`DONE`	Name of the producer-completion sentinel file. Defaults to `DONE`. Production can span several producers — they run one at a time, which `producer_file` enforces — so “a producer closed” is not “production finished”. This file is what says the latter, and only the last producer should write it.
`drain_on_read`	boolean	no	`true`	(Source only) Delete each chunk’s files once its message is acknowledged. Defaults to true — this is what makes the directory a queue rather than a growing archive. With it off, chunks are left in place. Acknowledged chunks are emitted at most once per consumer run; nacked chunks are redelivered.
`emit_done`	`never` \| `success` \| `end`	no	`never`	(Sink only) When to create `done_file`, marking production finished for a `stop_on_done` consumer. Defaults to `never`. See [`SpoolDone`]. Set it on the last producer only. A publisher opening the spool deletes an existing sentinel, since it is producing again.
`fsync`	`chunk` \| `off`	no	`chunk`	How hard to work at making a chunk survive a power loss. Defaults to `chunk`, which is two fsyncs per message with a sidecar. See [`SpoolFsync`].
`metadata_extension`	string	no	`json`	Extension of the JSON metadata sidecar, with or without the leading dot. Defaults to `json`. Set to an empty string to write and expect payload files only.
`naming_pattern`	string	no	`{seq:09}`	(Sink only) Name template for each chunk, without extension. Supports `{seq}`, `{seq:06}` / `{seq:06d}` (zero-padded), `{timestamp}` (unix millis) and `{message_id}`. Defaults to `{seq:09}`. Lexical order must match sequence order, so keep a zero-padded `{seq}` first.
`path`	string	yes	—	Directory holding the spool. Created if missing.
`payload_extension`	string	no	`bin`	Extension of the payload file, with or without the leading dot. Defaults to `bin`.
`poll_interval_ms`	integer	no	`100`	(Source only) Idle poll interval in milliseconds when the directory holds no new chunks. Defaults to 100.
`producer_file`	string	no	`PRODUCER`	Name of the file holding the producer lock, which keeps a second producer out. Defaults to `PRODUCER`. Every instance sharing the directory must agree on this name — that is what makes them exclude each other — and it must not collide with the other control files or with a chunk name. See [`SpoolClaim`].
`shard_depth`	integer	no	`0`	How many levels of shard subdirectory to spread chunks over. Defaults to 0, which writes every chunk straight into `path`. A flat spool is one directory per stream, and most filesystems degrade long before mq-bridge does: 30fps with sidecars is over 200,000 files an hour. Sharding takes the leading digits of the sequence number as directory names, so `{seq:09}` with a depth of 2 and a width of 3 writes chunk 1 as `000/000/001.bin` and gives every directory at most 1000 entries. Both ends must agree: a consumer only descends as far as its own `shard_depth`. It warns when a scan finds subdirectories it is not configured to enter, since the alternative is a spool that reads as permanently empty.
`shard_width`	integer	no	`3`	How many characters of the sequence number each shard level consumes. Defaults to 3, giving 1000 entries per level. Ignored when `shard_depth` is 0. With sharding on, `naming_pattern` must start with a zero-padded `{seq:0N}` wider than `shard_depth * shard_width`, so that every chunk shards identically and one character is left for the file itself.
`source_metadata`	boolean	no	`false`	(Source only) Include `mqb.src.spool_*` source positions in each message’s metadata. Defaults to false.
`stop_on_done`	boolean	no	`false`	(Source only) End the stream once the directory holds no unread chunks and `done_file` is present. Defaults to false, which tails the directory indefinitely. Both halves matter: a producer that finished long ago still has its backlog drained first, and a spool that is merely empty keeps the stream open, because another producer may still be coming.