The SLOYRA technical guide

Localised concise guide · based on documentation revision 0.1, 27 September 2026. This guide summarises the technical reference; it is not a complete translation of the implementation specification.

What SLOYRA does

SLOYRA coordinates protected content delivery, local caching and demand-aware storage placement. Files, images, documents, video recordings and streaming segments share a demand model. Frequently reused content can benefit from RAM and faster disks; less active content belongs on capacity-oriented media.

Local delivery caches and durable origin storage are separate systems. A cache can be rebuilt from origin. It does not replace Ceph replication, erasure coding or backups. Moving an object from SSD to HDD does not reduce its logical size.

Current package and target architecture

The customer package described in the source overview is version 2.1.74. It uses a dedicated Nginx configuration with secure_link and auth_request, plus a Python agent for licensing and content access. A native Nginx binary module is not included in that archive. Lua integration, C/Rust components, controller APIs and configuration contracts in the wider reference describe a target architecture.

The source reports component checks and installation checks with real Nginx on macOS and Linux x86_64. These checks do not establish real Ceph-cluster performance or compatibility with every platform listed in the design matrix.

Use the instructions for your release

The personalised ZIP contains README.md, docs/INSTALL.md, docs/LICENSING.md, docs/OPERATIONS.md and docs/API.md. These documents define actual commands and parameters. Version 2.1.74 sends a heartbeat every 60 seconds and uses an online authorisation lasting no more than 300 seconds. New requests stop after the last authorisation expires without connectivity. Signed renewal uses license-update.

Technical examples in this guide explain intended behaviour. Check your release capabilities before applying a proposed configuration or interface.

Target architecture summary. A documented component or API is not evidence that it ships in the current package.

Separate delivery from control

The delivery path resolves the content route, validates access, selects an immutable representation, checks local tiers and reads origin when needed. Nginx workers must not wait for full disk scans, telemetry uploads or Ceph migration jobs. Background work belongs to a local agent and placement controller with bounded queues.

Client -> access check -> RAM -> NVMe / SSD -> HDD -> Ceph origin
                              |
                    request and cache events
                              v
                   aggregate -> plan -> migrate

The diagram describes responsibilities, not an unconditional disk-by-disk read sequence. A location index and the configured policy determine the appropriate tier.

Identity and ownership

Cache identity includes the tenant, object, content version and representation. Chunked content also requires the chunk layout and index. Different versions must never be combined in one response. Tenant identifiers belong to trusted routing context, not arbitrary client headers.

The control plane validates configuration before publishing a new generation. New requests use the new generation only after preparation succeeds. Existing requests retain the resources they need until completion. Validation failure leaves the previous configuration active.

Failure boundaries

A failure in analytics must not stop content delivery that is otherwise authorised. Access checks remain mandatory. Queue limits must constrain memory use, and overload must have an explicit response rather than unlimited buffering.

The local cache is disposable. Ceph placement changes require stronger safety: copy the immutable source, verify its length and integrity, atomically switch the location catalog, wait for active-reader safeguards, and only then retire the old copy. Each stage must survive interruption and be auditable.

The native-module and Lua profiles below are design profiles. Use the configuration shipped with your package for installation.

Know which integration you have

The current documented package uses Nginx secure_link and auth_request with a Python agent. The broader specification proposes a dynamic HTTP module written in C17, Lua policies using a LuaJIT/Lua 5.1 profile, and a background agent. Do not add a proposed load_module entry unless the corresponding binary is present and qualified for your exact Nginx build.

An operating-system name alone does not establish compatibility. Record the Nginx version, build flags, architecture, libraries and module ABI. Test every enabled HTTP transport in the actual deployment.

Request phases

Resolve and normalise the route before evaluating the access policy. Complete authorisation before response headers or protected bytes are sent. Select one content version, locate its cache entries, coordinate a bounded fill if necessary, and report the final outcome.

Lua policy code should make bounded decisions using approved inputs. It must not run arbitrary blocking filesystem scans, shell commands or network operations in a worker. Background control operations use separate components.

Deploy and recover

Validate Nginx configuration before reloading, retain the previous known-good configuration and qualify graceful reload under active requests. Workers should keep resources from their configuration generation until those requests finish.

nginx -V
nginx -t

These are Nginx diagnostic commands, not a SLOYRA installer. Run them with the configuration path and permissions appropriate to your installation. The release documentation defines any SLOYRA-specific commands and service names.

Design principles and acceptance requirements. The exact signed-link format is defined by the installed release.

Authorise every request

Protected content requires a successful access check before any bytes are returned. This includes a cache hit, HEAD metadata and a conditional response such as 304. An invalid or expired authorisation results in 403; rate limiting and infrastructure failure have separate diagnostic causes.

A policy may bind a request to its method, normalised path, expiry, audience and allowed scope. The signer and verifier must agree on the exact canonical bytes. Test percent encoding, repeated query keys, Unicode, separators and authority handling; ambiguous forms must not accidentally grant access.

Separate permissions from caching

A shared cache key must not mix tenants or incompatible access scopes. Possession of a local cached copy is not permission to serve it. Revocation policy is independent of object popularity and cache freshness.

Do not log bearer tokens, URL signatures, private payloads or signing secrets. Diagnostic events should contain stable reason codes and only the identifiers needed to investigate an incident. An IP address alone is not a reliable user identity because of NAT, proxies and mobile networks.

Keys and incidents

Rotation needs explicit key identifiers, overlap rules and expiry handling. Keep signing material outside public configuration and verify that diagnostic exports redact secrets. A compromise response can revoke affected keys and tighten access policy without waiting for cache eviction.

These controls limit unauthorised requests and automated collection. They cannot prevent a legitimately authorised recipient from copying bytes already delivered. TLS, application security and secure link issuance remain part of the deployment.

Target delivery contract. Qualify each capability against the installed release.

Keep representation identity stable

The response belongs to one immutable content version and representation. Encoding variants may have different lengths and validators. Do not combine chunks from different versions, or change an ETag or content encoding after response headers have been committed.

Authorisation precedes representation metadata, preconditions and body delivery. HEAD has no body. Conditional requests retain their normal HTTP meaning regardless of which cache tier supplies the bytes.

Byte ranges

The design's baseline profile supports a single byte range for GET. Normalise start-end, start- and suffix forms against the known representation size. The closed-interval length is end - start + 1, with overflow and bounds checks. A valid partial response is 206; an unsatisfiable range uses 416 with the appropriate representation length.

The baseline design ignores multiple ranges and sends a full 200 response after other checks. Multipart ranges are a separate qualified profile; do not assume every build supports them.

One fill, many readers

Request collapse allows concurrent readers of the same missing content to share a fill. Each client remains a separate logical request. Waiter counts, deadlines and fill concurrency are bounded. An origin retry keeps the same fill identity but gets a new attempt identity.

Partial or corrupted fills must not become completed cache entries. After a client cancels, record the bytes actually sent; do not count the entire planned response as delivered. Measure origin attempts separately from logical demand. Slow clients need explicit buffer and time limits so one transfer cannot consume unbounded memory.

Summary of the proposed cache contract. Tier support and configuration come from the release manifest.

Roles of the tiers

RAM serves a small hot working set with a strict budget. NVMe and SATA/SAS SSD have different performance and operational profiles. HDD supplies capacity for reusable content that does not justify a faster tier. A lookup index and placement policy locate complete entries; the design does not require every request to scan every disk.

Cache keys include tenant, object, immutable version, representation and, where relevant, chunk layout. The same filename with a different digest is a new content identity. A new chunk size requires a new layout version.

Admission, freshness and eviction

Admission decides whether a fetched object should enter the cache. Eviction chooses which existing copies can be removed. Freshness determines whether a stored representation is still usable. These are different decisions: an object can be popular but stale, or valid but not worth admitting.

A single scan of a large catalog must not evict the useful working set. Consider request recurrence, object size, read cost and tenant quota. Reserve resources for buffers, indexes and metadata instead of allocating all RAM to payload.

Publication and recovery

Only complete, verified entries become visible. Shared fills need bounded waiting and cancellation behaviour. An interrupted fill stays unpublished; a corrupted entry is quarantined or discarded and read again from a trustworthy origin.

Apply backpressure before disks become full. Budget temporary files, in-flight writes, cleanup and active readers. Tenant quotas cannot exceed physical capacity. Local cache eviction must never delete the durable origin object, and a cache replica must never be counted as a backup.

Event names and scoring are proposed contracts, not a claim of a deployed public API.

Three separate event classes

Access denials do not heat protected content. HEAD can increase metadata demand but not body-byte demand. A lookup is not an additional popularity vote. Prefetch creates origin load without a customer request; retries create extra physical work without new logical demand.

Count the actual work

Keep requested_bytes, served_bytes and origin_bytes separate. A cancelled transfer can serve fewer bytes than requested. A failed origin attempt still contributes the bytes actually received. Record admitted, reused, prefetched and discarded bytes separately when supported.

For 100 authorised clients requesting the same 1 MiB chunk, ideal sharing means 100 logical requests, 100 MiB served and 1 MiB read from origin. A single cache miss count cannot express all three facts. This is arithmetic under stated assumptions, not a performance benchmark.

Time, confidence and duplicate delivery

Popularity uses explicit event time, decay windows and policy revisions. Decisions should be reproducible from the policy revision and input window. Delayed events, sampling and missing data affect confidence and must be visible.

Retries in telemetry delivery preserve event identity. Deduplicate by stable producer identity, epoch and sequence so replay cannot double demand. A real new client HTTP request is distinct. Bound identifier cardinality and resist artificial heating from scans or unauthorised traffic before enabling automatic placement.

Placement-controller design. The source overview does not establish validation against a real Ceph cluster.

Choose the adapter and owner

Ceph CRUSH rules and device classes select eligible OSD placement for pools. A popularity label alone does not move one object to a different device class. The design uses prepared hot and cold pools, or RGW storage classes, with an explicit adapter.

In managed RADOS mode, SLOYRA controls an immutable object namespace and a location catalog. In RGW mode, use supported S3-compatible operations and the capabilities of the deployed RGW release. Never move internal RGW fragments by directly editing its hidden RADOS objects.

Only one component owns migration policy for a namespace. Begin in observation mode, where recommendations do not move data. Qualify conditional-copy and version semantics before enabling managed actions.

Copy, verify, switch, retire

1. Confirm the source version, catalog generation, permitted destination and available reserve.
2. Copy to a new destination while keeping the source readable.
3. Verify content integrity and length against the immutable source.
4. Atomically switch the catalog with a generation check.
5. Respect active-reader barriers and the recovery policy.
6. Retire the old copy only when it is safe.

A source change or catalog conflict invalidates the old plan. Resume interrupted jobs from persisted state and reconcile the actual destination before retrying. Never delete the source merely because a copy request returned success.

Bound migration work

Reserve space for temporary copies and durability overhead. Limit migration bandwidth and concurrency independently from customer delivery. Respect Ceph health, quotas, pinning and failure domains. A degraded cluster or unsupported capability can require pausing migrations while continuing safe reads.

Measure different quantities separately

Logical bytes, physical origin bytes, local cache copies and temporary migration copies are different quantities. Moving an object from SSD to HDD changes the media requirement; it does not make the object's logical bytes disappear.

For replicated data, physical origin use is approximately logical data multiplied by the replica count, before metadata and reserves. Erasure coding has its own data/parity overhead. Keep durability equivalent when comparing a baseline with SLOYRA.

physical_origin ≈ logical_data × durability_overhead
required_capacity ≥ origin + local_cache + migration_reserve + operating_reserve

These formulas are planning models, not storage-accounting measurements. Real reports must state whether capacities are usable or raw, decimal or binary, and whether metadata is included.

Interpret savings carefully

The developer's source description includes a claim of savings up to 70%. The reference explicitly says this requires a published methodology and a reproducible protocol. This international guide does not present that figure as measured or guaranteed.

Less occupied SSD capacity, lower total cost and fewer physical copies are three separate outcomes. Cost modelling should include media prices, spare capacity, electricity, network traffic, SSD wear, operations and software licensing. Temporary migration copies and recovery headroom can materially change the result.

Run a fair comparison

Use the same corpus, request trace, retention, durability, hardware assumptions and service targets. Compare cold-start and steady-state behaviour. Report origin bytes, served bytes, occupancy by tier, migration traffic, latency, error rate and the observation period. Record every excluded cost and distinguish sample arithmetic from measured production performance.

Use the release compatibility matrix

The target server profile is Linux x86_64. Ubuntu LTS, Debian, Rocky Linux and AlmaLinux appear in the design matrix; their presence is not a compatibility certificate. ARM64 requires separate qualification. macOS component tests do not make macOS a qualified production delivery-server platform.

Record the exact OS, kernel, CPU architecture, Nginx version and build options, runtime libraries, filesystem, mount settings and Ceph client/cluster versions. A dynamic module must match the relevant Nginx ABI. System security updates and product compatibility are separate responsibilities.

Prepare the node

Inventory RAM, file descriptors, open connections and available storage. Reserve memory for the OS, worker processes, indexes, active buffers and background jobs. Check write permissions for cache and state directories without granting broad privileges. Separate public delivery, administrative control and telemetry access.

Plan DNS, TLS and outbound connectivity to the licence service. Validate time synchronisation because signatures and time-limited authorisations depend on clocks. Do not disable SELinux or AppArmor globally as a substitute for correct permissions.

Install the actual package

1. Download the personalised ZIP and licence credentials from the account after confirmed payment.
2. Read its README.md and docs/INSTALL.md before running commands.
3. Verify the supplied release identity and checksums where provided.
4. Follow the package's dependency, service and configuration instructions.
5. Test authorised delivery and denied access on both cold and warm caches.
6. Record the installed version and retain a tested rollback path.

The public reference does not establish a published package repository. Do not treat proposed CLI examples or similarly named third-party packages as the official installer. Your team performs installation, configuration and ongoing administration.

Daily checks

Observe delivery health separately from analytics and placement health. Watch access-denial reasons, latency, error rates, memory, file descriptors, cache occupancy, origin traffic and any telemetry backlog. Check time synchronisation and the licence service connection.

In the documented 2.1.74 package, the heartbeat period is 60 seconds and an online authorisation lasts at most 300 seconds. New requests are denied when the last authorisation expires without renewal. Plan connectivity and monitor expiry; do not assume a long offline grace period.

Configuration and release changes

Validate configuration, prepare a new generation, and activate it only if readiness checks succeed. Record the effective generation instead of assuming a file edit is live. Keep the previous known-good configuration. Release updates need compatibility checks, backups of durable control state and a rehearsed rollback.

Drain a node before maintenance: stop accepting new work according to the release procedure and wait for active work within bounded deadlines. Do not forcibly delete files still in use by readers or migration tasks.

Incident priorities

Preserve incident evidence without exporting secrets. A cache can be rebuilt, but catalog state, configuration, keys and other authoritative control data need a separate recovery plan. Recovery must retain access controls; never make protected routes public to conceal an outage.

Metric and event schemas in the extended reference are target contracts. Inspect the installed release for available names and endpoints.

Measure the path and its outcome

Observe logical requests, cache lookups and physical origin attempts independently. Record body bytes actually requested, delivered and fetched. HEAD, background prefetch and retries need distinct accounting. Keep error, miss and stale outcomes separate.

Hit rate by request can look good while large misses dominate traffic. Pair request hit rate with byte hit rate, origin throughput, latency distribution and error rate. Measure cache admission and later reuse to identify writes that never provide value.

Reliable event delivery

A producer's identity, epoch and sequence distinguish events across restarts. Retry delivery with the same identity. An acknowledgement must indicate what has been durably accepted, and partial-batch handling must distinguish accepted, rejected and retryable items.

Bound local telemetry storage and expose backlog size, age, dropped-event counts and confidence. Missing telemetry must reduce confidence in placement decisions instead of silently appearing as zero demand. Raw object identifiers and unbounded labels can overwhelm a metrics system; use a deliberate cardinality policy.

Keep an operational audit

Configuration activation, key rotation, placement plans, catalog switches and administrative actions require traceable outcomes. Record the actor's trusted scope, policy revision and relevant generations. Do not include signatures, tokens, secret configuration or content bodies.

Dashboards should show delivery and control-plane health separately. Alerts need an actionable condition, severity and runbook. A traffic graph or successful health response alone is insufficient evidence of correct access control or safe migration.

Build an evidence record

For each release, record the source revision, package digest, exact platform, Nginx build, libraries, configuration generation and test corpus. State whether a result is a unit check, component test, integration test, load test or production observation. A passing adapter-contract test is not a real Ceph integration test.

Use repeatable traces with known content versions, sizes and checksums. Keep benchmark duration, concurrency, warm-up and hardware limits in the report. Planned thresholds are acceptance goals, not published performance results.

Minimum behavioural checks

• Reject invalid, expired and cross-scope access on cold and warm caches.
• Verify GET, HEAD, conditional responses and supported ranges.
• Detect wrong lengths, corruption and attempts to mix versions.
• Bound shared-fill waiters, buffers and origin retries.
• Ensure duplicate telemetry delivery does not double demand.
• Test interrupted cache fills and recovery after process restart.
• Reject unsupported configuration and retain the previous active generation.
• Exercise licence expiry and signed renewal according to the actual package.

Placement failure points

Interrupt copy, verification, catalog switch and cleanup independently. Confirm that at least one safe authoritative copy remains. Test source-version changes, catalog conflicts, low disk space, active readers and degraded Ceph. Recovery must reconcile actual state before retrying a mutation.

Stop and investigate

Stop a test when protected bytes leak, a durable source is lost, data from different versions is mixed, or resources grow without bounds. Do not hide critical correctness defects inside average throughput.

Runbooks are also testable: an operator should be able to diagnose the condition, apply the documented action and verify recovery. Preserve the timeline and evidence, redact secrets and record unresolved limitations before approving an operational profile.

This is a concise guide to the proposed versioned schema. It is not a complete key-by-key reference or a ready-to-run configuration.

Types and explicit units

The proposed YAML schema uses strict booleans, bounded integers, finite ratios, enumerations and UTF-8 strings. Byte quantities specify B, KiB, MiB, GiB or TiB; durations specify ms, s, m, h or d. Do not assume an unlabelled number has the intended unit.

One KiB is 1024 bytes. Configuration normalisation uses integer bytes and milliseconds where defined. Event and metric contracts can use other explicit units, such as seconds; do not silently reuse a configuration unit.

Validation before activation

1. Enforce file size and nesting limits.
2. Reject duplicate YAML keys, unsupported tags and unknown fields.
3. Check types, ranges and relationships between fields.
4. Resolve approved secret references without exposing their values.
5. Check local paths, permissions and resource availability.
6. Calculate a digest of the normalised effective configuration.
7. Prepare policy, route and resource generations.
8. Activate atomically after readiness succeeds.

Failure during preparation preserves the active generation. Validation success is not activation success. A multi-node rollout reports readiness for each node.

Cross-field constraints

Total cache budgets must fit the node after reserves. A tenant quota cannot exceed the physical limit. Chunk layout changes require a new layout version. Migration needs destination capacity and compatible adapter capabilities. A missing setting must never make a protected route public.

Defaults come from the specific release manifest. Design-example values are laboratory assumptions, not guaranteed defaults. Combine separate YAML fragments structurally; repeating the same top-level key can discard settings in permissive parsers and is rejected by the target strict profile.

Design summary only. Proposed endpoints in the extended reference do not imply an available server or SDK. The package's docs/API.md is authoritative for its implemented interfaces.

Separate versions and authority

An API path version, telemetry schema_version and configuration server.schema_version identify different contracts. One does not substitute for another. Advertise capabilities explicitly and reject unsupported major versions.

The target local control surface uses a Unix domain socket; remote control uses authenticated TLS. Customer file delivery remains separate from administrative endpoints. A client-supplied role field or header cannot expand the authority granted by transport authentication.

Roles distinguish observation, telemetry production, configuration activation, placement planning, execution and catalog writing. Permission to publish telemetry is not permission to change placement.

Wire data and errors

JSON uses UTF-8, strict duplicate-key handling and bounded input sizes. Sizes are bytes; duration names include their units; absolute times use UTC. The design's integer range is 0..9007199254740991. Fractions, negative byte counts, NaN and infinity are not valid integer counters.

A stable error code describes the failure; human-readable wording is not a machine contract. A retryable flag allows a retry after a transient condition is addressed but does not guarantee success.

Idempotency and conflict control

Retrying a mutation requires an idempotency identity bound to its payload and scope. Catalog changes use generation checks and verified evidence of the destination state. A conflict must trigger reconciliation instead of overwriting newer placement.

Event delivery preserves producer identity, epoch and sequence across retries. Distinguish accepted and rejected items in partial batches. Acknowledgements represent durable acceptance, not proof that every downstream aggregate has already been recalculated. Redact secrets from audit records and diagnostics.

These are planning profiles, not measured release benchmarks. Use the same trace and constraints when comparing alternatives.

Match the cache unit to the workload

Keep metadata and payload policies separate

Repository indexes and live manifests can change while payload objects remain immutable. Their freshness policies must differ. A restarted live producer needs a new generation so an old sequence number cannot identify new bytes.

For software releases, an ideal cold edge fetches each shared chunk once, while every client remains a separate logical request. Several independent edges need independent fills unless an explicit shared layer exists. Do not assume global request collapse.

Allocate a combined resource budget

A deployment can serve several profiles, but their independent maximum budgets cannot simply be added. Reserve resources for metadata, interactive reads, bulk transfers and migration work. Concurrency reservations alone do not reserve bandwidth.

Revisit the profile when the corpus, range distribution, tenant count, retention or hardware changes. A new chunk size requires a new layout version and temporary capacity for old and new entries. Test cold start, cancellation, retry and restart for each profile before enabling automated placement.