If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dragonflyoss/dragonfly-archived shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 23+ active contributors
• Distributed ownership (top contributor 13% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dragonflyoss/dragonfly-archived repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dragonflyoss/dragonfly-archived.

What it runs against: a local clone of dragonflyoss/dragonfly-archived — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dragonflyoss/dragonfly-archived | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1195 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dragonflyoss/dragonfly-archived. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dragonflyoss/dragonfly-archived.git
#   cd dragonfly-archived
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dragonflyoss/dragonfly-archived and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dragonflyoss/dragonfly-archived(\\.git)?\\b" \\
  && ok "origin remote is dragonflyoss/dragonfly-archived" \\
  || miss "origin remote is not dragonflyoss/dragonfly-archived (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/dfget/app/root.go" \\
  && ok "cmd/dfget/app/root.go" \\
  || miss "missing critical file: cmd/dfget/app/root.go"
test -f "cmd/supernode/app/root.go" \\
  && ok "cmd/supernode/app/root.go" \\
  || miss "missing critical file: cmd/supernode/app/root.go"
test -f "cmd/dfdaemon/app/root.go" \\
  && ok "cmd/dfdaemon/app/root.go" \\
  || miss "missing critical file: cmd/dfdaemon/app/root.go"
test -f "client/client.go" \\
  && ok "client/client.go" \\
  || miss "missing critical file: client/client.go"
test -f "apis/types" \\
  && ok "apis/types" \\
  || miss "missing critical file: apis/types"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1195 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1165d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dragonflyoss/dragonfly-archived"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Dragonfly is a peer-to-peer (P2P) file distribution system designed for efficient large-scale file downloads across networks, particularly in container image distribution and CI/CD scenarios. It uses a supernode architecture (see Dockerfile.supernode) to coordinate peers in sharing file chunks, dramatically reducing bandwidth consumption on origin servers by leveraging peer-to-peer transfers. Monorepo structured as: apis/types/ contains protocol type definitions (peer_create_request.go, task_info.go, etc.), client/client.go provides the client SDK, with separate Dockerfiles for supernode and regular daemon. Build system uses Makefile; CI/CD via CircleCI (.circleci/config.yml) and Travis (.travis.yml).

DevOps engineers and platform teams managing container registries, artifact distribution, and large-scale deployments who need to reduce egress bandwidth costs and accelerate downloads across thousands of nodes. Contributors are typically infrastructure and distributed systems engineers.

ARCHIVED AND DEPRECATED — This repository is no longer maintained; the project has moved entirely to dragonflyoss/Dragonfly2. The codebase shows Go 1.12 dependencies (dated), CircleCI + Travis CI setup, and organized GitHub issue templates, suggesting it was production-ready before archival. Do not use for new projects.

Critical risk: This repo is archived and unmaintained. Go 1.12 dependencies are severely outdated (released 2019), creating security vulnerabilities. All development has migrated to Dragonfly2; merging PRs here is impossible. Using this in production exposes you to unpatched CVEs and compatibility issues with modern Go toolchains.

Nothing. This repository is archived. All active development occurs in https://github.com/dragonflyoss/Dragonfly2. The last commits and PRs are frozen; the CHANGELOG.md, ROADMAP.md, and adopters.md document the legacy state.

Do not clone this repo for new work. If you must examine it historically: git clone https://github.com/dragonflyoss/dragonfly-archived.git && cd dragonfly-archived && make (requires Go 1.12+, though this will fail with modern toolchains). Instead, use Dragonfly2: https://github.com/dragonflyoss/Dragonfly2

Daily commands: This repo does not run. For historical reference, the Makefile likely supports make build and make test, but Go 1.12 is required and unavailable on modern systems. See Dragonfly2 for working builds: git clone https://github.com/dragonflyoss/Dragonfly2 && cd Dragonfly2 && make build

• cmd/dfget/app/root.go — Entry point for dfget CLI tool—primary download client that all developers must understand to grasp the request lifecycle
• cmd/supernode/app/root.go — Entry point for supernode (coordinator)—core peer-discovery and task-management service that orchestrates all P2P transfers
• cmd/dfdaemon/app/root.go — Entry point for dfdaemon—local proxy that intercepts HTTP requests and coordinates downloads with supernode
• client/client.go — Main HTTP client abstraction for supernode communication—handles all task creation, peer info, and preheat requests
• apis/types — API contract definitions (task, peer, preheat, piece structures)—essential to understand request/response semantics across all components
• dfdaemon/downloader/downloader.go — Core download orchestration logic in daemon—manages P2P and direct HTTP fallback strategies
• dfdaemon/proxy/cert.go — HTTPS proxy certificate handling in daemon—critical for transparent HTTPS interception without client modification

Add a New Supernode API Endpoint

1. Define the request struct in apis/types/ (e.g., new_feature_request.go) with JSON tags (apis/types/new_feature_request.go)
2. Define the response struct in apis/types/ (e.g., new_feature_response.go) (apis/types/new_feature_response.go)
3. Add a new method to client/client.go that POSTs to the supernode endpoint (client/client.go)
4. Create a client/new_feature.go with the full request logic (similar to client/task_create.go) (client/new_feature.go)
5. Update cmd/supernode/app/root.go to register the HTTP handler (cmd/supernode/app/root.go)

Add a New Download Strategy

1. Implement the downloader interface in dfdaemon/downloader/ (similar to p2p/dfclient.go) (dfdaemon/downloader/strategy_name/strategy.go)
2. Register the strategy in dfdaemon/downloader/downloader.go as a fallback option (dfdaemon/downloader/downloader.go)
3. Add configuration flags in dfdaemon/config/config.go to enable/disable the strategy (dfdaemon/config/config.go)
4. Add constants for timeouts/retries in dfdaemon/constant/constant.go (dfdaemon/constant/constant.go)

Add a New Daemon Request Type

1. Define the parameter struct with validation logic (similar to param_handler.go) (dfdaemon/handler/param_handler.go)
2. Create a new handler method in dfdaemon/handler/root_handler.go (dfdaemon/handler/root_handler.go)
3. Add route mapping in cmd/dfdaemon/app/root.go or root_handler startup (cmd/dfdaemon/app/root.go)
4. Define error cases in dfdaemon/exception/errors.go (dfdaemon/exception/errors.go)

• Go 1.12 + gRPC-like HTTP RPC — Efficient concurrent I/O for peer coordination and P2P piece transfers; simple HTTP API reduces operational complexity vs gRPC
• HTTP/HTTPS transparent proxy in dfdaemon — Intercepts client downloads without code changes; MITM certificates enable HTTPS support without CA trust modifications
• Supernode central coordinator — Tracks task metadata and peer availability; enables intelligent peer selection and piece replication without DHT complexity
• Piece-based chunking (configurable size) — Allows granular P2P parallelism; clients can pull different pieces from different peers simultaneously
• Heartbeat + task-aware scheduling — Maintains liveness of peers; dynamically routes requests to fastest/closest peers based on piece availability

• Centralized supernode vs decentralized DHT

  • Why: Centralization simplifies peer discovery and reduces network overhead; trade-off is single point of failure (mitigated via backup supernodes)
  • Consequence: Easier operations but requires reliable supernode deployment; supernode becomes bottleneck at scale

• HTTP RPC over gRPC

  • Why: Simpler debugging, fewer dependencies, easier proxy interception; gRPC would require protocol-aware proxies
  • Consequence: Slightly higher overhead per RPC but dramatically simpler architecture; easier troubleshooting with curl/tcpdump

• Piece-based download with configurable piece size

  • Why: Balances parallelism (small pieces) vs peer disk overhead (large pieces); allows tuning per use case
  • Consequence: Adds complexity in piece tracking and reassembly; requires coordination with supernode

This is archived code; nothing runs. Specific gotchas: (1) Go 1.12 is required but unsupported on modern systems—go.mod lacks version constraints for most dependencies, relying on exact commit hashes that may no longer resolve; (2) CI uses deprecated CircleCI v1 syntax (.circleci/config.yml); (3) swagger.yml references undefined or missing endpoint implementations in unshown code; (4) no environment variable documentation exists—legacy supernodes likely required DATABASE_URL, PEER_PORT, etc., but unspecified.

• P2P (Peer-to-Peer) File Distribution — Dragonfly's core mechanism; understanding how peers register, exchange pieces, and report progress to a supernode is essential to modifying protocol or scaling logic.
• Supernode Architecture — The central coordinator in Dragonfly; it tracks active tasks, maintains peer registries, and assigns download sources. Modifications to task scheduling or piece allocation require understanding this pattern.
• Chunk-based Download / Piece Protocol — Files are split into small pieces; peers download pieces from each other and the origin. Understanding piece_info.go, piece_pull_request.go, and piece_update_request.go requires knowing how chunking affects parallelism and failure recovery.
• Task Registration and Lifecycle Management — Tasks (downloads) are registered with the supernode, tracked via task_create_request.go and task_info.go, and updated until completion. Changes to task TTL, retry logic, or state machines modify these types.
• Heartbeat-based Health Monitoring — Peers send heart_beat_request.go to the supernode to report liveness and metrics. The supernode uses this to detect dead peers and reassign pieces. Reliability improvements here are critical.
• OpenAPI / Swagger for API Definition — apis/swagger.yml defines the REST contract; understanding OpenAPI is necessary to add new endpoints, validate against the spec, and generate client code from the definition.
• Container Image Pull Optimization — Dragonfly's primary use case is accelerating Docker image pulls (via apis/types/cdn_source.go and source server abstraction). Understanding image layer structure and pull semantics is essential for real-world contributions.

• dragonflyoss/Dragonfly2 — The active successor to this archived project; all development and maintenance now occurs here with modernized Go, Rust components, and Kubernetes integration.
• distribution/distribution — Docker's official image registry implementation; Dragonfly often integrates as a proxy or mirror for OCI image distribution in similar use cases.
• moby/moby — Docker Engine; Dragonfly peers run as daemons on Docker hosts to accelerate image pulls via P2P, making this a key integration point.
• opencontainers/image-spec — OCI standard for container image format and distribution; Dragonfly operates at the layer that pulls and caches OCI images efficiently.
• restic/restic — Another Go-based distributed backup tool using peer-sync patterns; comparable architectural approach to coordinating large data transfers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for client/peer_*.go operations

The client package has multiple peer operation files (peer_create.go, peer_delete.go, peer_info.go, peer_list.go) but only peer_create.go and peer_delete.go appear to have corresponding test files. peer_info.go and peer_list.go lack test coverage. Given that these are core API client operations, adding unit tests would improve reliability and serve as documentation for new contributors.

• [ ] Create client/peer_info_test.go with tests for peer info retrieval operations
• [ ] Create client/peer_list_test.go with tests for peer listing and filtering
• [ ] Add mock fixtures to client/client_mock_test.go for peer-related responses
• [ ] Ensure tests cover both success and error paths following existing test patterns in client_test.go

Add missing API type validations and tests for apis/types/*.go

The apis/types directory contains 26+ type definition files representing request/response objects, but there are no corresponding validation tests. Many of these types likely have business logic constraints (e.g., task_info.go, peer_create_request.go, preheat_info.go). Adding validators and tests would catch invalid states early and document expected field constraints.

• [ ] Create apis/types/validation_test.go to test type field validations
• [ ] Add unit tests for critical types: task_create_request.go, peer_create_request.go, and preheat_create_request.go
• [ ] Implement validation methods (Validate()) on types that accept user input
• [ ] Document field constraints in type comments (e.g., required fields, valid ranges)

Add GitHub Actions workflow to replace deprecated Travis CI (.travis.yml)

The repo uses .travis.yml for CI, which is outdated. There's a .circleci/config.yml but no modern GitHub Actions workflow. Adding a GitHub Actions workflow (.github/workflows/test.yml) would provide better integration with the archived repo's GitHub interface and serve as a template/reference for the new Dragonfly2 repository.

• [ ] Create .github/workflows/ci.yml with Go 1.12+ test, lint, and build steps
• [ ] Reference .golangci.yml configuration for linting setup
• [ ] Add test coverage reporting using codecov or similar
• [ ] Include build step using Makefile targets and validate against Dockerfile dependencies

• Document the supernode configuration model: apis/types/ lacks request types for supernode setup (e.g., no supernode_config_request.go). Add a proposal and types for configuring peer limits, task expiration, and rate limiting—useful for understanding the coordinator role.
• Add missing test files for protocol types: apis/types/ has ~30 .go files but no corresponding _test.go files. Pick 3 types (e.g., peer_info.go, task_info.go, piece_info.go) and write marshaling/unmarshaling tests to validate JSON serialization—educational for understanding the protocol.
• Audit and document Go dependency security issues: go.mod lists dependencies from 2017–2019 (e.g., pkg/errors v0.8.0, uuid v0.0.0-20180122). Create a SECURITY.md documenting known CVEs and recommend users migrate to Dragonfly2 immediately—low code but high-impact awareness contribution.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.