hpr_documentation/ccdn/ccdn_architecture_upgrades.md

ccdn_architecture_upgrades.md

CCDN Architecture Upgrade Ideas

This document lists potential improvements to the CCDN architecture that were identified during a design review. None of these are considered essential for the initial release; they are intended as future enhancements once the core system is stable.

The philosophy remains unchanged:

• Keep the system simple.
• Prefer proven Unix tools.
• Avoid unnecessary dependencies.
• Preserve the stateless nature of edge nodes.

---

1. Atomic Content Deployment

Priority: High

Instead of synchronising directly into the live content directory, use a staging directory.

Suggested workflow:

1. Download the signed control file.
2. Verify its signature.
3. Synchronise content into a staging directory.
4. Perform validation.
5. Atomically rename the staging directory into production.
6. Reload nginx if required.

Benefits:

• Prevents partially updated content from being served.
• Makes interrupted synchronisations harmless.
• Provides clean rollback behaviour if validation fails.

---

2. Content Manifest

Priority: High

Publish a manifest alongside the content containing:

• filename
• size
• SHA-256 checksum
• modification time

After synchronisation, each node can verify downloaded files against the manifest.

Benefits:

• Detects storage corruption.
• Detects incomplete synchronisations.
• Simplifies troubleshooting.
• Provides confidence that mirrors contain identical content.

---

3. Configuration Versioning

Priority: Medium

Include a version number or timestamp in the signed control file.

Example:

{
    "version": 14
}

or

{
    "generated": "2026-08-01T12:00:00Z"
}

Benefits:

• Easier troubleshooting.
• Prevents accidental rollback.
• Makes monitoring simpler.

---

4. Configuration Expiry

Priority: Medium

Include an expiry timestamp in the signed control file.

Example:

{
    "valid_until": "2026-09-01T00:00:00Z"
}

Nodes should continue serving existing content if the configuration expires, but generate warnings or alerts so administrators know updates are no longer being received.

Benefits:

• Detects long-term communication failures.
• Helps identify replay attacks using stale configurations.

---

5. Health Endpoint

Priority: Medium

Expose a small JSON document such as:

/health.json

Example information:

• configuration version
• last successful synchronisation
• current origin
• disk usage
• software version
• node identifier

Benefits:

• Simplifies monitoring.
• Easy integration with Prometheus or external monitoring.
• Useful during troubleshooting.

---

6. Disk Space Protection

Priority: Medium

Before synchronisation, verify sufficient free disk space exists.

If available space falls below a configured threshold, abort the update and generate an alert.

Benefits:

• Prevents failed deployments.
• Protects nodes from filling the filesystem.

---

7. SSH Restrictions

Priority: Medium

Restrict the rsync account so it cannot obtain an interactive shell.

Possible approaches include:

• rrsync
• ForceCommand
• command= restrictions in authorized_keys

Benefits:

• Reduces the impact of a compromised SSH key.
• Limits access strictly to file synchronisation.

---

8. Signing Key Rotation

Priority: Low

Support publishing both the current and next public signing keys.

This allows new keys to be distributed before they become active.

Benefits:

• Simplifies planned key rotation.
• Avoids emergency replacement procedures.

---

9. Split Configuration Files

Priority: Low

If the control file becomes large, consider splitting it into independently signed files.

For example:

• origins.json
• sync.json
• nginx.json
• security.json

Benefits:

• Easier maintenance.
• Smaller updates.
• Simpler reviews.

This is not recommended until the configuration grows significantly.

---

10. Declarative Configuration Only

Priority: Ongoing

The signed configuration should describe desired system state rather than commands to execute.

For example:

Prefer:

• sync interval
• fail2ban settings
• nginx options
• origin list

Avoid:

• arbitrary shell commands
• remote script execution

Benefits:

• Smaller attack surface.
• Easier auditing.
• More predictable behaviour.

---

Future Enhancements

These ideas are intentionally outside the scope of the first implementation but may become useful if CCDN grows.

• Delta manifests for large libraries.
• Geographic origin selection.
• Optional peer-to-peer mirror synchronisation.
• Compression for text-based metadata.
• Signed content release tags.
• Read-only content mounts between updates.

---

Deliberately Out of Scope

The following technologies are intentionally excluded from the CCDN design:

• Kubernetes
• Docker Swarm
• Redis
• PostgreSQL
• Elasticsearch
• Message queues
• Dynamic service discovery
• Distributed databases
• Complex orchestration systems

The goal is to keep CCDN easy to understand, easy to operate, and easy to recover by relying on mature Unix tooling rather than additional infrastructure.