README
¶
Nexo
English | Italiano
Nexo is an object store compatible with the Amazon S3 API, written in Go. A single binary
(nexo) contains the S3 server, the Admin API and the web console; nexoctl is the CLI for data and
administration. The same binary runs on one drive, on multiple drives with erasure coding and as a
multi-node cluster, with no external metadata database.
- S3 API: SigV4, buckets, objects, multipart, versioning, Object Lock, lifecycle, notifications, CORS,
checksums, SSE-S3/SSE-KMS/SSE-C encryption, presigned URLs and POST policies; passes all 451 applicable tests
of the Ceph
s3-testssuite and the 638 of MinIO'smintSDK suites, on single drive, multiple drives and cluster. - Durability: Reed-Solomon erasure coding with configurable parity, bitrot protection, automatic healing, hot drive replacement, expansion with new pools.
- Security: IAM users, groups and policies, access keys with expiry, STS, access rules with glob and regex, revocable share links, TLS with hot reload, mTLS between nodes, built-in KMS or KES, audit log.
- Distributions: a bucket served on custom domains CloudFront style, with ACME certificates, signed URLs, in-memory and on-disk cache with automatic invalidation.
- Operations: web console, Prometheus metrics with ready-made Grafana dashboard and alerts, real-time trace and logs, OpenTelemetry, deb/rpm packages, Homebrew, Docker images, Helm chart, systemd unit.
Screenshots
The overview of the web console (shown in dark mode when your browser prefers it). The images are
taken from a demo deployment with make screenshots; drive capacity is shown as 4 × 1 TiB for illustration.
 Object browser: folders, uploads, versions, previews and share links |
 Bucket lifecycle: expiration, noncurrent versions and incomplete uploads |
 IAM policy editor: AWS policy JSON with completion, validation and a visual builder |
 Access rules: allow and deny by prefix, glob or regex, with conditions |
 Distributions: buckets served on custom domains, with TLS and traffic |
 Distribution cache: hit ratio, bandwidth saved and top domains |
 Monitoring: requests, errors, latency and bandwidth of every node |
 Cluster: pools, erasure sets, nodes and drives at a glance |
 Users: IAM users with their policies and groups |
 Sign in: the console uses the same access keys as the S3 API |
Quick start
With Docker:
docker run -d --name nexo -p 9000:9000 -p 9001:9001 \
-e NEXO_ROOT_USER=admin -e NEXO_ROOT_PASSWORD=supersecret \
-v nexo-data:/data paolor/nexo:latest server /data
The images are on Docker Hub: paolor/nexo (server and CLI) and
paolor/nexoctl (CLI only).
With the binary (releases or make build):
export NEXO_ROOT_USER=admin NEXO_ROOT_PASSWORD=supersecret
nexo server ~/nexo-data # absolute path; multiple drives: nexo server /mnt/disk{1...4}
Then open the console at http://localhost:9001 (user admin, password supersecret) or use the CLI:
nexoctl alias set local http://localhost:9000 admin supersecret
nexoctl mb local/photos
nexoctl cp hello.txt local/photos/
nexoctl share download --expire 2h local/photos/hello.txt # revocable link
Any S3 client works with the endpoint http://localhost:9000 and the same credentials, for example
aws --endpoint-url http://localhost:9000 s3 ls.
Documentation
📖 Documentation site: https://r3n3r0.github.io/Nexo/ (Italian: https://r3n3r0.github.io/Nexo/it/), with search, the CLI reference and the Admin API.
The same pages are in docs/user, in English with an Italian translation next to every
page (<page>.it.md; also at https://github.com/R3n3r0/Nexo/tree/main/docs/user, for those reading this file
from a release archive):
| Quickstart | the complete walkthrough in five minutes |
| Installation | binaries, deb/rpm, Homebrew, Docker, Compose, Helm, systemd |
| Deployment modes | single drive, multiple drives, cluster, sizing |
| Configuration | flags, environment variables, dynamic configuration |
| Operations guide | monitoring, healing, upgrades, backup, troubleshooting |
| Security | policies, sharing, access rules, TLS, KMS |
| Distributions and cache | custom domains, with a complete tutorial |
| Reference | CLI, Admin API, S3 compatibility |
make docs-site publishes it as a static site with MkDocs (in bin/site, in English and in Italian under /it/).
Project documents
| # | Document | Contents |
|---|---|---|
| 1 | Architecture | Components, repository layout, stack, technical choices |
| 2 | Features | Catalog of the server, dashboard and CLI features, differences from S3 |
| 3 | Cluster | Topology, erasure coding, quorum, distributed locks, healing, expansion |
| 4 | API | Supported S3 APIs, Admin API, internode RPC |
| 5 | Roadmap and tasks | Milestones, tasks with IDs, dependencies and acceptance criteria, status |
| 6 | Test plan | Strategy and test cases for server, CLI, dashboard and cluster |
| 7 | Security and operations | Threat model, TLS, KMS, observability |
| 8 | Modes and release | Deployment modes, packaging and release process |
| 9 | Presigned URLs, policies and sharing | Presigned URLs, POST policies, policies, revocable share links |
| 10 | Access, domains and distributions | Access rules, domains, distributions behind proxies |
| 11 | Per-domain cache | Memory/disk cache, per-level policies, invalidation, cluster cache |
| 12 | Service architecture | Binding convention for services, routes and composition in internal/app |
The changes of every release are in the CHANGELOG; the test coverage of every feature in the catalog is in the traceability matrix.
Development
You need Go (the version in go.mod) and, for the console, Node.js.
| Command | What it runs |
|---|---|
make build |
React console and the bin/nexo and bin/nexoctl binaries with the console embedded (make build-go: Go only) |
make test / make test-race |
Go tests (unit and in-process integration in the three modes) |
make test-integration |
S3/IAM/presigned integration suite in every mode, slow tests included |
make test-cluster |
cluster tests with 4 real bin/nexo processes (kill, pause, restart) |
make test-s3compat |
Ceph s3-tests compatibility suite |
make lint / make web-lint / make web-test / make e2e |
Go lint, console lint and tests, Playwright |
make run-cluster |
local cluster of 4 processes with S3 on 127.0.0.1:9101, 9103, 9105, 9107 and the console on the next port (Linux) |
make docs / make docs-check |
CLI reference in docs/user/cli |
make traceability / make traceability-check |
feature → test matrix in test/TRACEABILITY.md |
make security |
govulncheck, gosec and npm audit |
make zap-scan |
authenticated OWASP ZAP active scan of the Admin API from api/openapi.yaml against bin/nexo (needs Java; test/security/zap-api-scan.sh) |
make screenshots |
regenerates the console screenshots in docs/images/screenshots from a seeded demo deployment (Playwright; scripts/screenshots) |
make dco |
the sign-off check of the pull requests on the commits of the branch (CONTRIBUTING.md) |
make help |
all the targets |
The code follows the convention of docs/12: every service has
an interface and an unexported implementation, and composition happens only in internal/app.
License
Nexo is free software licensed under the GNU Affero General Public License v3.0 only
(AGPL-3.0-only): if you modify it and let users interact with it over a network, you must offer them the
source code of your version. The NOTICE file adds attribution terms (AGPL section 7(b)): keep it, and
keep "Powered by Nexo (https://github.com/R3n3r0/Nexo)" in the legal notices of the user interface. Organizations
that cannot comply with the AGPL can buy a commercial license from the copyright holder;
contributions are accepted under the terms of CONTRIBUTING.md. Archives, deb/rpm packages,
container images and the Helm chart carry LICENSE (and NOTICE in archives and packages).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
nexo
command
Command nexo is the Nexo object storage server.
|
Command nexo is the Nexo object storage server. |
|
nexoctl
command
Command nexoctl is the Nexo command-line client.
|
Command nexoctl is the Nexo command-line client. |
|
tools/traceability
command
Command traceability writes the traceability matrix of docs/06 §6.8 (test/TRACEABILITY.md): every feature of the catalog with the tests that cover it.
|
Command traceability writes the traceability matrix of docs/06 §6.8 (test/TRACEABILITY.md): every feature of the catalog with the tests that cover it. |
|
internal
|
|
|
app
Package app composes the Nexo server: it wires service implementations to their interfaces according to the configuration and the detected deployment mode, builds the S3 and console HTTP servers and runs them as a lifecycle.Group.
|
Package app composes the Nexo server: it wires service implementations to their interfaces according to the configuration and the detected deployment mode, builds the S3 and console HTTP servers and runs them as a lifecycle.Group. |
|
cli
Package cli holds the nexoctl building blocks used by the cobra commands (internal/cli/commands): the alias configuration store and service, the S3Client contract with its aws-sdk-go-v2 implementation, the parsing of targets, sizes and durations, the transfer engine of cp, mv, mirror and rm, the anonymous access presets and the output helpers (tables, JSON Lines, progress bar, stable exit codes).
|
Package cli holds the nexoctl building blocks used by the cobra commands (internal/cli/commands): the alias configuration store and service, the S3Client contract with its aws-sdk-go-v2 implementation, the parsing of targets, sizes and durations, the transfer engine of cp, mv, mirror and rm, the anonymous access presets and the output helpers (tables, JSON Lines, progress bar, stable exit codes). |
|
cli/clitest
Package clitest provides the test doubles of the nexoctl commands: MemS3 is an in-memory S3 store that drives the generated mock of cli.S3Client with RunAndReturn (docs/12 §12.2 rule 8: no hand-written fake of an interface that has a mock; the shared state is modeled on the mock).
|
Package clitest provides the test doubles of the nexoctl commands: MemS3 is an in-memory S3 store that drives the generated mock of cli.S3Client with RunAndReturn (docs/12 §12.2 rule 8: no hand-written fake of an interface that has a mock; the shared state is modeled on the mock). |
|
cli/commands
Package commands holds the cobra commands of nexoctl (docs/02 §2.3).
|
Package commands holds the cobra commands of nexoctl (docs/02 §2.3). |
|
clock
Package clock abstracts time so that services can be tested deterministically.
|
Package clock abstracts time so that services can be tested deterministically. |
|
config
Package config holds the static server configuration: the settings read once at startup from command-line flags, NEXO_* environment variables and an optional JSON file, with precedence flags > env > file > defaults.
|
Package config holds the static server configuration: the settings read once at startup from command-line flags, NEXO_* environment variables and an optional JSON file, with precedence flags > env > file > defaults. |
|
domain
Package domain holds the types and sentinel errors shared by every Nexo service and transport.
|
Package domain holds the types and sentinel errors shared by every Nexo service and transport. |
|
lifecycle
Package lifecycle defines the start/stop contract of long-running components and a Group that manages them in order.
|
Package lifecycle defines the start/stop contract of long-running components and a Group that manages them in order. |
|
service
Package service groups the Nexo services: one sub-package per service, each with its contract in service.go, an unexported implementation created by New(deps, opts...) and a generated mock in mock/ (docs/12-service-architecture.md).
|
Package service groups the Nexo services: one sub-package per service, each with its contract in service.go, an unexported implementation created by New(deps, opts...) and a generated mock in mock/ (docs/12-service-architecture.md). |
|
service/accessrule
Package accessrule manages the access rules of the buckets (docs/10 §10.1): rules with a priority, an effect, principals, actions, a key pattern (prefix, glob or RE2 regex, internal/service/match) and conditions, stored in the bucket metadata and evaluated by the policy engine as a resource-based source next to the bucket policy (Evaluator implements policy.AccessRules).
|
Package accessrule manages the access rules of the buckets (docs/10 §10.1): rules with a priority, an effect, principals, actions, a key pattern (prefix, glob or RE2 regex, internal/service/match) and conditions, stored in the bucket metadata and evaluated by the policy engine as a resource-based source next to the bucket policy (Evaluator implements policy.AccessRules). |
|
service/admin
Package admin is the facade used by the Admin API and the CLI for server-wide operations (information, data usage, healing, service control) and the home of the business rules of the console that span several domain services:
|
Package admin is the facade used by the Admin API and the CLI for server-wide operations (information, data usage, healing, service control) and the home of the business rules of the console that span several domain services: |
|
service/audit
Package audit records who did what (S-OPS-06, docs/05 T-8.4): one Entry per request served by the S3 API and the Admin API (identity, operation, resource, client, outcome, latency, request id, node, sizes), written to the structured log of the server, kept in memory for the searches of the console (D-MON-03, aggregated over the nodes of a cluster) and delivered to the audit targets of the dynamic configuration (audit_webhook, audit_kafka), each with the persistent queue of the notification targets (internal/service/event).
|
Package audit records who did what (S-OPS-06, docs/05 T-8.4): one Entry per request served by the S3 API and the Admin API (identity, operation, resource, client, outcome, latency, request id, node, sizes), written to the structured log of the server, kept in memory for the searches of the console (D-MON-03, aggregated over the nodes of a cluster) and delivered to the audit targets of the dynamic configuration (audit_webhook, audit_kafka), each with the persistent queue of the notification targets (internal/service/event). |
|
service/auth
Package auth defines request authentication: AWS Signature V4 for headers, presigned query strings, streaming aws-chunked payloads (signed chunks, unsigned chunks with trailers) and POST policies, plus the signer that produces signed requests, presigned URLs and POST policy forms.
|
Package auth defines request authentication: AWS Signature V4 for headers, presigned query strings, streaming aws-chunked payloads (signed chunks, unsigned chunks with trailers) and POST policies, plus the signer that produces signed requests, presigned URLs and POST policy forms. |
|
service/bucket
Package bucket manages bucket metadata: versioning, policy, lifecycle, object lock, encryption, quota, tags, CORS and notification configuration.
|
Package bucket manages bucket metadata: versioning, policy, lifecycle, object lock, encryption, quota, tags, CORS and notification configuration. |
|
service/cache
Package cache implements the HTTP cache of the distributions (docs/11): reusable cache policies inherited from the cluster to the distribution, the domain and the behavior; a memory tier (W-TinyLFU) and an optional disk tier with quotas per cluster, distribution and domain; the invalidations, automatic on every write of the object layer and manual (paths, patterns, tags, domains, everything, soft or hard), propagated to every node with a sequence number; the shared mode of a cluster, where a key has an owner node chosen by rendezvous hashing; the purge webhooks of the CDNs and proxies in front of the cluster; the warm-up, the inspector and the statistics.
|
Package cache implements the HTTP cache of the distributions (docs/11): reusable cache policies inherited from the cluster to the distribution, the domain and the behavior; a memory tier (W-TinyLFU) and an optional disk tier with quotas per cluster, distribution and domain; the invalidations, automatic on every write of the object layer and manual (paths, patterns, tags, domains, everything, soft or hard), propagated to every node with a sequence number; the shared mode of a cluster, where a key has an owner node chosen by rendezvous hashing; the purge webhooks of the CDNs and proxies in front of the cluster; the warm-up, the inspector and the statistics. |
|
service/certs
Package certs manages the TLS certificates of the domains of the distributions (docs/10 §10.2 "TLS and per-domain certificates"): the certificates uploaded by the operators (PEM chain and key, validated: chain linkage, key matching the leaf, DNS names, validity) and the ones obtained and renewed with ACME (RFC 8555: Let's Encrypt, ZeroSSL, any ACME CA) through the HTTP-01, the TLS-ALPN-01 or the DNS-01 challenge.
|
Package certs manages the TLS certificates of the domains of the distributions (docs/10 §10.2 "TLS and per-domain certificates"): the certificates uploaded by the operators (PEM chain and key, validated: chain linkage, key matching the leaf, DNS names, validity) and the ones obtained and renewed with ACME (RFC 8555: Let's Encrypt, ZeroSSL, any ACME CA) through the HTTP-01, the TLS-ALPN-01 or the DNS-01 challenge. |
|
service/certs/dns01
Package dns01 publishes the TXT records of the ACME DNS-01 challenge (RFC 8555 §8.4) in the DNS zones of the distributions and waits for them to be served by the authoritative nameservers of the zone, before the certificate service asks the CA to validate them.
|
Package dns01 publishes the TXT records of the ACME DNS-01 challenge (RFC 8555 §8.4) in the DNS zones of the distributions and waits for them to be served by the authoritative nameservers of the zone, before the certificate service asks the CA to validate them. |
|
service/cluster
Package cluster holds the services that make the nodes of a deployment one cluster (docs/03 §3.5, §3.9): the startup sequence (Bootstrapper: same topology on every node, quorum of drives per set, coordinated format.json), the broadcast of cache invalidations (Notifier), the aggregated server information and clock checks (Info) and the leader election of the singleton background jobs (Leader).
|
Package cluster holds the services that make the nodes of a deployment one cluster (docs/03 §3.5, §3.9): the startup sequence (Bootstrapper: same topology on every node, quorum of drives per set, coordinated format.json), the broadcast of cache invalidations (Notifier), the aggregated server information and clock checks (Info) and the leader election of the singleton background jobs (Leader). |
|
service/config
Package config is the dynamic configuration service: key/value settings grouped by subsystem (e.g.
|
Package config is the dynamic configuration service: key/value settings grouped by subsystem (e.g. |
|
service/crypto
Package crypto is the server-side encryption of the objects (docs/02 S-OBJ-13, docs/05 T-7.5): it seals and unseals the object keys and encrypts the object data in a DARE-like package format.
|
Package crypto is the server-side encryption of the objects (docs/02 S-OBJ-13, docs/05 T-7.5): it seals and unseals the object keys and encrypts the object data in a DARE-like package format. |
|
service/distribution
Package distribution implements the distributions of docs/10 §10.2: a distribution exposes a bucket (or a prefix of it) on one or more custom domains, in the "website" mode (static sites, downloads: index document, SPA fallback, error pages, redirects, behaviors per path, signed URLs and cookies) or in the "s3" mode (the domain is an S3 endpoint aliasing the bucket).
|
Package distribution implements the distributions of docs/10 §10.2: a distribution exposes a bucket (or a prefix of it) on one or more custom domains, in the "website" mode (static sites, downloads: index document, SPA fallback, error pages, redirects, behaviors per path, signed URLs and cookies) or in the "s3" mode (the domain is an S3 endpoint aliasing the bucket). |
|
service/erasure
Package erasure implements the Reed-Solomon erasure coding of the object layer and the bitrot protection of the shards it produces.
|
Package erasure implements the Reed-Solomon erasure coding of the object layer and the bitrot protection of the shards it produces. |
|
service/event
Package event implements bucket notifications (S-BKT-10): S3-format events published by the object layer and the S3 transport, routed by the notification configuration of their bucket (and by the filters of the targets) to the configured targets: webhook, Kafka, NATS, AMQP, Redis and PostgreSQL.
|
Package event implements bucket notifications (S-BKT-10): S3-format events published by the object layer and the S3 transport, routed by the notification configuration of their bucket (and by the filters of the targets) to the configured targets: webhook, Kafka, NATS, AMQP, Redis and PostgreSQL. |
|
service/heal
Package heal is the healing service of the erasure-coded deployments (docs/03 §3.7): it repairs objects and buckets through the object layer's Healer and reports the state of every drive before and after, drains the MRF queue (the writes that missed a drive and the reads that met damaged data), formats the empty drives found in an existing deployment and heals them completely with a checkpoint that survives restarts (healing.bin), and runs the healing jobs of the Admin API (nexoctl admin heal).
|
Package heal is the healing service of the erasure-coded deployments (docs/03 §3.7): it repairs objects and buckets through the object layer's Healer and reports the state of every drive before and after, drains the MRF queue (the writes that missed a drive and the reads that met damaged data), formats the empty drives found in an existing deployment and heals them completely with a checkpoint that survives restarts (healing.bin), and runs the healing jobs of the Admin API (nexoctl admin heal). |
|
service/health
Package health exposes liveness, readiness and cluster health checks.
|
Package health exposes liveness, readiness and cluster health checks. |
|
service/iam
Package iam manages identities: the root user, users, groups, service accounts (access keys with inline policies and expiry) and STS temporary credentials, plus the policies attached to users and groups.
|
Package iam manages identities: the root user, users, groups, service accounts (access keys with inline policies and expiry) and STS temporary credentials, plus the policies attached to users and groups. |
|
service/ilm
Package ilm implements the bucket lifecycle (S-BKT-07, docs/05 T-7.3): the LifecycleConfiguration documents of S3 (parsing and validation), their evaluation against the versions of a key and the in-progress multipart uploads with an injected clock (Expiration, expired object delete markers, NoncurrentVersionExpiration, AbortIncompleteMultipartUpload; transitions to remote tiers are P2), and their application: by the background scanner, which hands every version to the service (scanner.Lifecycle), or on demand (ApplyNow).
|
Package ilm implements the bucket lifecycle (S-BKT-07, docs/05 T-7.3): the LifecycleConfiguration documents of S3 (parsing and validation), their evaluation against the versions of a key and the in-progress multipart uploads with an injected clock (Expiration, expired object delete markers, NoncurrentVersionExpiration, AbortIncompleteMultipartUpload; transitions to remote tiers are P2), and their application: by the background scanner, which hands every version to the service (scanner.Lifecycle), or on demand (ApplyNow). |
|
service/kms
Package kms is the key management service of the server-side encryption (docs/07 §7.2, docs/05 T-7.5).
|
Package kms is the key management service of the server-side encryption (docs/07 §7.2, docs/05 T-7.5). |
|
service/lock
Package lock defines the namespace locking used to serialize access to buckets and objects.
|
Package lock defines the namespace locking used to serialize access to buckets and objects. |
|
service/logs
Package logs is the log stream of the server (S-OPS-07, docs/05 T-8.3): the slog handler of the process is a tee (Service.Handler) that writes the records to the output of the server (JSON or text, with a level and a format changed at runtime by the "logger" subsystem of the dynamic configuration, Configurator) and keeps them in a ring buffer of recent entries that the subscribers (the console, the CLI) receive live, from every node of the cluster (Peer).
|
Package logs is the log stream of the server (S-OPS-07, docs/05 T-8.3): the slog handler of the process is a tee (Service.Handler) that writes the records to the output of the server (JSON or text, with a level and a format changed at runtime by the "logger" subsystem of the dynamic configuration, Configurator) and keeps them in a ring buffer of recent entries that the subscribers (the console, the CLI) receive live, from every node of the cluster (Peer). |
|
service/match
Package match compiles and evaluates the key patterns of the access rules (docs/10 §10.1) and of the distribution behaviors (§10.2): literal prefixes, globs and RE2 regular expressions, matched against keys normalized so that an encoding never bypasses a rule.
|
Package match compiles and evaluates the key patterns of the access rules (docs/10 §10.1) and of the distribution behaviors (§10.2): literal prefixes, globs and RE2 regular expressions, matched against keys normalized so that an encoding never bypasses a rule. |
|
service/metrics
Package metrics is the metrics registry of a node.
|
Package metrics is the metrics registry of a node. |
|
service/object
Package object defines the object layer: the logical S3 API over buckets, objects, versions and multipart uploads.
|
Package object defines the object layer: the logical S3 API over buckets, objects, versions and multipart uploads. |
|
service/policy
Package policy is the policy engine: parsing and validation of AWS-format policy documents, evaluation of IAM policies, group policies, inline (session) policies and bucket policies, the policy simulator, the simplified anonymous-access presets and the store of named IAM policies with their attachments to users and groups.
|
Package policy is the policy engine: parsing and validation of AWS-format policy documents, evaluation of IAM policies, group policies, inline (session) policies and bucket policies, the policy simulator, the simplified anonymous-access presets and the store of named IAM policies with their attachments to users and groups. |
|
service/preflight
Package preflight validates the configuration of a node without starting anything nor writing to its drives: the checks of "nexo server --dry-run" (docs/08 §8.3, TM-12).
|
Package preflight validates the configuration of a node without starting anything nor writing to its drives: the checks of "nexo server --dry-run" (docs/08 §8.3, TM-12). |
|
service/quota
Package quota enforces the hard quotas of the buckets (docs/02 S-BKT-09, docs/05 T-7.7).
|
Package quota enforces the hard quotas of the buckets (docs/02 S-BKT-09, docs/05 T-7.7). |
|
service/ratelimit
Package ratelimit is the request rate limiter of a node (S-OPS-10, S-DST-08): token buckets keyed by client address, access key or user, bucket and distribution, and the concurrency limit of the S3 API (api.requests_max, api.requests_deadline).
|
Package ratelimit is the request rate limiter of a node (S-OPS-10, S-DST-08): token buckets keyed by client address, access key or user, bucket and distribution, and the concurrency limit of the S3 API (api.requests_max, api.requests_deadline). |
|
service/scanner
Package scanner is the background scanner (docs/03 §3.7): a continuous cycle over every bucket and object of the deployment that computes the data usage (per bucket and per top-level prefix: objects, versions, delete markers, bytes) saved in .nexo.sys/usage.json and served to the Admin API, heals a sample of the objects (one every N, with a deep bitrot verification every M cycles), aborts the stale multipart uploads and hands every version to the lifecycle hook (ILM, M7).
|
Package scanner is the background scanner (docs/03 §3.7): a continuous cycle over every bucket and object of the deployment that computes the data usage (per bucket and per top-level prefix: objects, versions, delete markers, bytes) saved in .nexo.sys/usage.json and served to the Admin API, heals a sample of the objects (one every N, with a deep bitrot verification every M cycles), aborts the stale multipart uploads and hands every version to the lifecycle hook (ILM, M7). |
|
service/session
Package session manages console sessions: login with access/secret key yields a signed token stored by the transport in an HttpOnly cookie, plus a CSRF token, bound to the session, the browser sends back in a header.
|
Package session manages console sessions: login with access/secret key yields a signed token stored by the transport in an HttpOnly cookie, plus a CSRF token, bound to the session, the browser sends back in a header. |
|
service/settings
Package settings applies the dynamic configuration (config.Service) to the server: it reads the subsystems the server honors at every call, so that a change written through the Admin API takes effect on the next request without a restart (hot reload), and it decorates the services whose behavior depends on them.
|
Package settings applies the dynamic configuration (config.Service) to the server: it reads the subsystems the server honors at every call, so that a change written through the Admin API takes effect on the next request without a restart (hot reload), and it decorates the services whose behavior depends on them. |
|
service/share
Package share manages revocable share links (docs/09 §9.1 "Revoking shared links").
|
Package share manages revocable share links (docs/09 §9.1 "Revoking shared links"). |
|
service/storage
Package storage defines StorageAPI, the contract for accessing a single drive: metadata files (xl.meta), data parts and volume (bucket) directories.
|
Package storage defines StorageAPI, the contract for accessing a single drive: metadata files (xl.meta), data parts and volume (bucket) directories. |
|
service/storage/storagetest
Package storagetest is the behavior suite of storage.StorageAPI.
|
Package storagetest is the behavior suite of storage.StorageAPI. |
|
service/sysstore
Package sysstore keeps the system documents of a deployment (identities, named policies, dynamic configuration, bucket metadata, share links, session revocations) on the system volume of the drives of the first erasure set (.nexo.sys/config), whatever the deployment mode: the drives are storage.StorageAPI values, local or remote (internode RPC), so that every node of a cluster reads and writes the same documents (docs/03 §3.9: "bucket/IAM metadata: written with quorum").
|
Package sysstore keeps the system documents of a deployment (identities, named policies, dynamic configuration, bucket metadata, share links, session revocations) on the system volume of the drives of the first erasure set (.nexo.sys/config), whatever the deployment mode: the drives are storage.StorageAPI values, local or remote (internode RPC), so that every node of a cluster reads and writes the same documents (docs/03 §3.9: "bucket/IAM metadata: written with quorum"). |
|
service/topology
Package topology parses the server command line into a deployment layout.
|
Package topology parses the server command line into a deployment layout. |
|
service/trace
Package trace holds the request tracing of the server:
|
Package trace holds the request tracing of the server: |
|
testutil
Package testutil starts Nexo in-process for integration tests: free ports, temporary drive directories and test credentials, in every deployment mode (docs/08 §8.1): a single drive (SNSD), several drives of one node (SNMD, Drives) or a distributed cluster of several nodes running in the test process (StartCluster), each on its own ports, in front of an in-process load balancer.
|
Package testutil starts Nexo in-process for integration tests: free ports, temporary drive directories and test credentials, in every deployment mode (docs/08 §8.1): a single drive (SNSD), several drives of one node (SNMD, Drives) or a distributed cluster of several nodes running in the test process (StartCluster), each on its own ports, in front of an in-process load balancer. |
|
testutil/dnstest
Package dnstest runs an authoritative DNS server in the tests of the ACME DNS-01 challenge.
|
Package dnstest runs an authoritative DNS server in the tests of the ACME DNS-01 challenge. |
|
testutil/redaction
Package redaction holds the request every redaction of the server is tested with (the stderr logs, the log stream, the audit, the access logs and the live trace): one table, one predicate (domain.IsSensitiveParam).
|
Package redaction holds the request every redaction of the server is tested with (the stderr logs, the log stream, the audit, the access logs and the live trace): one table, one predicate (domain.IsSensitiveParam). |
|
tools/traceability
Package traceability builds the traceability matrix of docs/06 §6.8: every feature of the catalog (docs/02-features.md) mapped to the tests that declare to cover it with a "covers:" tag (Go tests, testscript scripts, Vitest and Playwright specs, test scripts).
|
Package traceability builds the traceability matrix of docs/06 §6.8: every feature of the catalog (docs/02-features.md) mapped to the tests that declare to cover it with a "covers:" tag (Go tests, testscript scripts, Vitest and Playwright specs, test scripts). |
|
transport/http/admin
Package admin implements the Admin API transport (/api/v1): JSON in, JSON out, problem+json errors (RFC 9457) with a stable snake_case code.
|
Package admin implements the Admin API transport (/api/v1): JSON in, JSON out, problem+json errors (RFC 9457) with a stable snake_case code. |
|
transport/http/console
Package console serves the embedded React dashboard: static assets with long-lived caching, index.html with no-cache and a SPA fallback for every non-API path, plus baseline security headers.
|
Package console serves the embedded React dashboard: static assets with long-lived caching, index.html with no-cache and a SPA fallback for every non-API path, plus baseline security headers. |
|
transport/http/dist
Package dist is the HTTP transport of the distributions (docs/10 §10.2): the routing of the requests by Host (HostRouter), the website routes (WebsiteRoutes), the HTTP-01 challenges of ACME (ChallengeRoutes), the metrics and the access log of every distribution.
|
Package dist is the HTTP transport of the distributions (docs/10 §10.2): the routing of the requests by Host (HostRouter), the website routes (WebsiteRoutes), the HTTP-01 challenges of ACME (ChallengeRoutes), the metrics and the access log of every distribution. |
|
transport/http/httpx
Package httpx holds the HTTP helpers shared by every transport: response encoding (XML, JSON, problem+json, S3 errors), the S3 error table, request-id generation and x-amz-* header helpers.
|
Package httpx holds the HTTP helpers shared by every transport: response encoding (XML, JSON, problem+json, S3 errors), the S3 error table, request-id generation and x-amz-* header helpers. |
|
transport/http/middleware
Package middleware defines the Middleware contract and the cross-cutting HTTP middlewares: request ids, panic recovery, logging, CORS, metrics, authentication and body limits.
|
Package middleware defines the Middleware contract and the cross-cutting HTTP middlewares: request ids, panic recovery, logging, CORS, metrics, authentication and body limits. |
|
transport/http/s3
Package s3 implements the S3 API transport.
|
Package s3 implements the S3 API transport. |
|
transport/http/server
Package server implements the HTTP server service: it owns the listener, optional TLS, HTTP/2, graceful shutdown and the chi router on which the registered Routes and Middlewares are mounted.
|
Package server implements the HTTP server service: it owns the listener, optional TLS, HTTP/2, graceful shutdown and the chi router on which the registered Routes and Middlewares are mounted. |
|
transport/rpc
Package rpc is the internode transport of a distributed deployment (docs/03 §3.4): HTTP/2 on the S3 port under Prefix (cleartext h2c, or TLS when the server has certificates), msgpack bodies, binary streams with framing and checksums for the data, and short-lived HS256 JWTs signed with a key derived from the root credentials and the deployment id.
|
Package rpc is the internode transport of a distributed deployment (docs/03 §3.4): HTTP/2 on the S3 port under Prefix (cleartext h2c, or TLS when the server has certificates), msgpack bodies, binary streams with framing and checksums for the data, and short-lived HS256 JWTs signed with a key derived from the root credentials and the deployment id. |
|
transport/rpc/rpctest
Package rpctest runs a distributed deployment inside the test process: N nodes on 127.0.0.1 with their own port, drives in a temporary directory, internode RPC over cleartext HTTP/2 and the cluster services (bootstrap, distributed locks, notifier, leader, info) wired like the composition root wires them.
|
Package rpctest runs a distributed deployment inside the test process: N nodes on 127.0.0.1 with their own port, drives in a temporary directory, internode RPC over cleartext HTTP/2 and the cluster services (bootstrap, distributed locks, notifier, leader, info) wired like the composition root wires them. |
|
version
Package version exposes the build information injected at link time with -ldflags "-X github.com/r3n3r0/nexo/internal/version.Version=...".
|
Package version exposes the build information injected at link time with -ldflags "-X github.com/r3n3r0/nexo/internal/version.Version=...". |
|
pkg
|
|
|
nexoadmin
Package nexoadmin is the Go client of the Nexo Admin API (/api/v1, documented by api/openapi.yaml).
|
Package nexoadmin is the Go client of the Nexo Admin API (/api/v1, documented by api/openapi.yaml). |
|
test
|
|
|
cluster
Package cluster holds the multi-process cluster tests of Nexo (docs/06 §6.3, TC-*): every test builds a deployment of several bin/nexo processes on 127.0.0.1, each on its own S3 and console ports with its drives in a temporary directory, and drives it through real clients (aws-sdk-go-v2 and the Admin API client) while it stops, pauses, kills and restarts the processes.
|
Package cluster holds the multi-process cluster tests of Nexo (docs/06 §6.3, TC-*): every test builds a deployment of several bin/nexo processes on 127.0.0.1, each on its own S3 and console ports with its drives in a temporary directory, and drives it through real clients (aws-sdk-go-v2 and the Admin API client) while it stops, pauses, kills and restarts the processes. |
|
compose
Package compose holds the tests of the Docker Compose deployments of deploy/docker (docs/08 §8.6): TM-06 (a container of the cluster stopped under load: no client error) and TM-09 (presigned and share links generated behind the nginx load balancer, downloaded from outside).
|
Package compose holds the tests of the Docker Compose deployments of deploy/docker (docs/08 §8.6): TM-06 (a container of the cluster stopped under load: no client error) and TM-09 (presigned and share links generated behind the nginx load balancer, downloaded from outside). |
|
proxy
Package proxy holds the tests of Nexo behind several reverse proxies (docs/10 §10.2 "Behind one or more proxies", §10.6 TCD-01..03, docs/11 §11.12 TCC-C-05, docs/09 TPS-19 on the custom domains of the distributions).
|
Package proxy holds the tests of Nexo behind several reverse proxies (docs/10 §10.2 "Behind one or more proxies", §10.6 TCD-01..03, docs/11 §11.12 TCC-C-05, docs/09 TPS-19 on the custom domains of the distributions). |
|
upgrade
Package upgrade holds the upgrade tests of Nexo (docs/05 T-9.8, docs/06 §6.1): the release under test takes over the drives written by the release before it, and the release before it may take them back.
|
Package upgrade holds the upgrade tests of Nexo (docs/05 T-9.8, docs/06 §6.1): the release under test takes over the drives written by the release before it, and the release before it may take them back. |
|
Package web embeds the compiled React console into the server binary when built with the "embedui" tag.
|
Package web embeds the compiled React console into the server binary when built with the "embedui" tag. |
Click to show internal directories.
Click to hide internal directories.