Flareless

Flareless is for the engineers who built the edge, kept it alive, carried the pager, solved the incidents, and then got told they were expendable.

This project gives that anger somewhere useful to go.

Not a rant. Not a boycott. Not a revenge repo.

A build.

An open source edge router and runtime prototype for programmable request handling, multi CDN failover, provider neutral traffic control, and resilient internet delivery.

Important

Flareless does not treat peer delivery as blind fallback. Route policy, integrity checks, provider health, and failure scope decide what happens next.

Note

The current public demo is static. It simulates CDN timeout behavior, HTTP status failover, peer assisted fallback, and policy controlled origin fallback without requiring a worker, backend, or paid hosting.

Current Status

This table is intentionally near the top so the repo stays honest about what is implemented now and what is still planned.

Feature	Status
Multi provider routing	Prototype implemented
Provider timeout failover	Prototype implemented
HTTP status failover	Prototype implemented
Route scoped health	Prototype implemented
Failure point tracking	Implemented
Route trace object	Implemented
Agent route trace analysis	Implemented
Agent recommendation report	Implemented
Static public demo	Implemented as simulation
Peer fallback	JSON fallback response only
Real peer chunk transfer	Not implemented
Hash verified peer bytes	Not implemented
Signed manifests	Not implemented
Distributed health checks	Not implemented
Durable production control plane	Not implemented

The strongest current identity is failure aware route control with agent assisted recommendations. The peer assisted delivery path is being prepared, but it is not yet a production peer CDN.

Mobile Demo

https://deerspotter.github.io/flareless/demo/

The mobile demo is static and requires no worker, backend, or paid hosting. It simulates provider timeout, HTTP status failover, peer assisted fallback, and route policy behavior for origin fallback.

Start Here

• Quickstart explains how to run the local runtime, tests, and simulator.
• Mobile Demo contains a no hosting mobile browser demo for timeout failover, HTTP failover, peer fallback, and origin fallback behavior.
• Honest Feedback is the blunt current project review, including what is strong, what is overclaimed, and what should happen next.
• Failure Point Tracking explains how Flareless records where a route broke before agent recommendations or fallback decisions.
• Roadmap breaks the project into contributor ready modules.
• Milestones defines the build phases and exit criteria.
• Architecture explains request flow, provider selection, health, manifests, and peer fallback.
• Optional Micro CDN Module explains the optional community micro CDN prototype.
• Micro CDN Protocol Draft defines node registration, content registration, routing responses, and v1 constraints.
• Micro CDN Node Agent explains how a node caches, serves, advertises, and deletes approved content.
• Micro CDN Coordinator explains local coordinator state, endpoints, routing purpose, and current limits.
• Contributing explains how to contribute without needing private context.
• Security explains trust boundaries, peer rules, provider routing rules, and secret handling.
• Code of Conduct keeps the project sharp without letting it become personal.

Core Idea

Most websites depend on one edge provider for DNS, TLS, WAF, caching, routing, and DDoS protection. That creates a single operational and policy failure point.

Flareless separates those functions.

flowchart LR
    U[User] --> STL[Smart Traffic Layer]
    STL --> A[CDN A]
    STL --> B[CDN B]
    STL --> C[CDN C]
    STL --> P[Peer Assisted Fallback Path]
    A --> D[Routed Response]
    B --> D
    C --> D
    P --> V[Future Hash and Manifest Verification]
    V --> D
    STL --> O{Origin fallback allowed?}
    O -->|yes| OS[Origin Storage]
    O -->|no| S[Stop safely]

Loading

If one CDN fails, blocks traffic, rate limits the site, or becomes unreachable, traffic can route around it.

Warning

Origin fallback should remain policy controlled. A provider failure should not automatically bypass peer verification, route policy, or content ownership rules.

Optional Micro CDN Module

Flareless also includes an optional micro CDN prototype under modules/micro-cdn.

The micro CDN module lets a node operator explicitly opt in to caching and serving approved public static files. It is not an exit node, not arbitrary proxying, and not private traffic inspection.

The current prototype supports:

approve public content path
cache local file
verify SHA256
store cached bytes by hash
advertise content to coordinator
route by public /mcdn path
serve cached content from node
persist coordinator state
persist node manifest
delete cached content
unadvertise deleted content

The public path model is:

/mcdn/{namespace}/{displayPath}

Example:

/mcdn/demo/hello.txt

Internally, nodes store bytes by hash:

cache/sha256/{first-two-hash-chars}/{full-sha256}

This keeps the user facing path readable while making the hash the source of truth.

Current Build

src/          Worker runtime prototype
services/     Go control plane scaffold
public/       Browser side peer logic
scripts/      Local runner and simulation tools
tests/        Node test suite
demo/         Static mobile browser demo

Local checks:

npm install
npm test
go test ./...
go build ./...

Local provider chain integration test:

npm test

The integration test covers this route sequence:

cdn-a times out
cdn-b returns 429
cdn-c succeeds

Expected route evidence:

x-flareless-provider: cdn-c
x-flareless-reason: PROVIDER_TIMEOUT_FAILOVER
x-flareless-attempts: cdn-a:PROVIDER_TIMEOUT,cdn-b:PROVIDER_BLOCKED_429,cdn-c:PROVIDER_SUCCESS
x-flareless-failure-points: 1:PROVIDER_TIMEOUT:cdn-a:PROVIDER_TIMEOUT,2:PROVIDER_BLOCKED_STATUS:cdn-b:PROVIDER_BLOCKED_429
x-flareless-route-trace: encoded routeTrace JSON

Route trace shape:

routeTrace = {
  requestId,
  routeKey,
  policyId,
  attempts,
  failurePoints,
  selectedFallback,
  finalStatus
}

Agent route trace analysis:

curl -X POST http://localhost:8787/agent/cdn-control \
  -H "content-type: application/json" \
  -d '{"routeTrace":{"requestId":"trace-001","routeKey":"route:/video/example/v1","policyId":"video-public-peer-first","attempts":[{"provider":"cdn-a","result":"PROVIDER_TIMEOUT"}],"failurePoints":[],"selectedFallback":null,"finalStatus":{"outcome":"provider-success","statusCode":200,"provider":"cdn-b","reason":"PROVIDER_TIMEOUT_FAILOVER"}}}'

Local runner:

npm run local

Timeout failover demo:

npm run demo:timeout-failover

Expected demo result:

cdn-a:PROVIDER_TIMEOUT
cdn-b:PROVIDER_SUCCESS
x-flareless-provider: cdn-b
x-flareless-reason: PROVIDER_TIMEOUT_FAILOVER

Simulator:

npm run simulate

Mobile browser demo:

https://deerspotter.github.io/flareless/demo/

The demo is static and requires no worker, backend, or paid hosting. It simulates provider timeout, HTTP status failover, peer assisted fallback, and route policy behavior for origin fallback.

Design Goals

• Multi CDN routing
• Provider independent origin storage
• Health based failover
• Versioned immutable content paths
• Client side video chunk fallback
• Optional peer assisted delivery
• Optional onion access for emergency reachability
• No single CDN control point
• Cloudflare style edge worker language without Cloudflare dependency

Recommended Architecture

Registrar
  |
Independent DNS
  |
Traffic Director
  |
  |---- CDN Provider A
  |---- CDN Provider B
  |---- CDN Provider C
  |
Object Storage Origin
  |
Versioned Content
  |
Optional Peer Assisted Layer
  |
Optional Onion Bootstrap

Why Parallel CDNs

CDNs should not be chained.

Bad:

User -> CDN A -> CDN B -> CDN C -> Origin

If CDN A fails, everything fails.

Good:

User
  |---- CDN A
  |---- CDN B
  |---- CDN C
  |---- Peer Fallback

Each route is independent.

Example Content Path

/video/show-name/episode-001/v17/720p/chunk-0001.ts

Use versioned paths instead of overwriting live files.

Failover Logic

flowchart TD
    R[Request arrives] --> A[Try primary CDN]
    A -->|success| OK[Return response with route headers]
    A -->|timeout| B[Try next ranked CDN]
    A -->|403, 404, 429, or 5xx| B
    B -->|success| OK
    B -->|all CDNs failed| P[Return peer fallback response]
    P -->|future verified chunks| OK
    P -->|peer unavailable| O{Origin fallback allowed?}
    O -->|yes| OR[Fetch from origin]
    O -->|no| SAFE[Fail closed safely]

Loading

Provider fetches are timeout aware. Each provider can define timeoutMs; when a provider does not answer before its deadline, Flareless records the timeout, marks that provider as failed, and tries the next ranked provider.

Successful routed responses include explanation headers:

x-flareless-provider: cdn-b
x-flareless-route-id: route-id
x-flareless-reason: PROVIDER_TIMEOUT_FAILOVER
x-flareless-attempts: cdn-a:PROVIDER_TIMEOUT,cdn-b:PROVIDER_SUCCESS

Health Check Signals

Each CDN route should be checked from multiple regions.

DNS success
TLS success
HTTP status
Time to first byte
Chunk download speed
Error rate
Provider specific block response

Edge Routing Flow

Incoming request
  |
Check route health table
  |
Select best healthy CDN
  |
Rewrite request to selected provider
  |
Return response or redirect

Security Model

Assume every external node can fail or behave maliciously.

Required controls:

• Hash verified chunks
• Signed manifests
• Provider independent TLS
• Rate limits
• Abuse reporting process
• Clear content ownership
• Origin access restrictions
• No private key sharing with peers

Caution

Peer assisted delivery should only serve approved public content. It should not become an arbitrary proxy, exit node, or private traffic relay.

License

MIT