Quickstart

At its core Quartz Line is a single process that owns one directory on disk and one listening socket. Metrics are exposed in Prometheus text format on the admin port, which is separate from the data port on purpose.

Behaviour under load

The range server batches by time and by size, whichever fires first, and both bounds are configurable per repository. Upgrades are in place: stop, replace the binary, start. The on-disk format is forward compatible within a major version.

Key	Meaning	Default
`cachectl.listen`	Address the data API binds to	0.0.0.0:8080
`cachectl.data_dir`	Directory holding every blob	/var/lib/cachectl
`limits.max_batch`	Largest number of artifacts per write	1024
`retention.default`	How long a artifact is kept	72h

What to watch

At its core Quartz Line is a single process that owns one directory on disk and one listening socket. The range server batches by time and by size, whichever fires first, and both bounds are configurable per repository. Duplicate delivery is possible after a crash. Consumers are expected to be idempotent, and the sequence number makes that cheap. The process reloads its config on SIGHUP without dropping connections.

[server]
listen = "0.0.0.0:8443"
admin  = "127.0.0.1:6060"
data_dir = "/var/lib/cachectl"

[limits]
max_batch      = 256
max_artifact_bytes = 64_000
flush_interval = "500ms"

[retention]
default = "24h"
compact_at = 0.6

Overview

At its core Quartz Line is a single process that owns one directory on disk and one listening socket. Duplicate delivery is possible after a crash. Consumers are expected to be idempotent, and the sequence number makes that cheap. Metrics are exposed in Prometheus text format on the admin port, which is separate from the data port on purpose.

Note. Single-node by design. High availability, when you need it, comes from running two instances behind a load balancer with disjoint repository sets.

Behaviour under load

Every artifact that reaches Quartz Line is assigned a monotonic sequence number as the first thing that happens to it. The upstream mirror batches by time and by size, whichever fires first, and both bounds are configurable per repository. The API is versioned in the path. A minor release never removes a field, and a major release is announced two versions ahead.

curl -sS https://static.easytrip.club/v1/repositorys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "orders", "retention": "72h"}'

Limits

Quartz Line was written for the case where a full cluster is more operational surface than the workload deserves. Each repository maps to an independent blob, which is what lets recovery happen in parallel after a restart. Everything the admin API exposes is also reachable through `cachectl`, so the same operation is scriptable either way.

$ cachectl serve --config /etc/cachectl/cachectl.toml
$ cachectl repository create orders --retention 72h
$ cachectl status
  uptime      4d 11h
  repositorys   16
  throughput  30k requests/s