RFC: Multi-Phase Publishing, Distribution, and Artifact Lifecycle Strategy for ReliaDL

[purvanshjoshi]

RFC: Multi-Phase Publishing, Distribution, and Artifact Lifecycle Strategy for ReliaDL

1. Executive Summary and Objectives

ReliaDL (PxA-Labs/ReliaDL) has evolved into a production-grade, fault-tolerant download manager and SHA verification engine with advanced capabilities including per-chunk cryptographic hashing, SOCKS5 and HTTP CONNECT proxy tunneling, token bucket rate limiting, and Prometheus telemetry cataloging.

To maximize user adoption across diverse ecosystems--ranging from Python developers importing the library to DevOps engineers running background containerized daemons and desktop CLI users--this Request for Comments (RFC) outlines a comprehensive, phased distribution and publishing roadmap.

The primary objective is to make ReliaDL accessible across all major distribution channels while maintaining strict security controls, build provenance, and manageable operational overhead.

---

2. Target Audience Segmentation and Distribution Channels

Target Audience	Primary Need	Recommended Channel	Delivery Mechanism
Python Application Developers	Programmatic library import (import reliadl)	PyPI (Python Package Index)	pip install reliadl
DevOps / SRE / Cloud Engineers	Background daemon with Prometheus scraping	Container Registries (GHCR / Docker Hub)	docker run ghcr.io/pxa-labs/reliadl
CLI & Desktop Power Users	Zero-dependency standalone command-line executable	GitHub Releases / Homebrew / WinGet	Direct binary download or package manager
Enterprise / Infrastructure Teams	Verified, reproducible software with SBOMs	Signed GitHub Release Artifacts	SLSA provenance and Sigstore signatures

---

3. Phased Rollout Roadmap

Phase 1: Core Library and Documentation Foundation (Immediate / Priority 1)

Phase 1 establishes the canonical package presence with minimal operational friction.

1. PyPI (Python Package Index)

• Package Format: Build Python Source Distribution (sdist) and Universal Binary Wheel (.whl) using standard PEP 517/518 build backends (build, flit_core, or hatchling).
• Publishing Mechanism: Implement PyPI Trusted Publishing via OIDC (OpenID Connect) in GitHub Actions, eliminating the need for long-lived API tokens.
• Naming & Namespace: Claim and reserve reliadl on PyPI. Include full package classifiers for Python versions (3.10, 3.11, 3.12, 3.13) and OS compatibility (OS Independent).

2. Canonical GitHub Releases

• Release Automation: Automate release creation on Git tag pushes matching v*.*.*.
• Release Assets: Include source archives, wheels, SHA-256 checksum manifests, and automated changelogs.

3. Hosted Documentation

• Platform: Deploy comprehensive documentation using Read the Docs or GitHub Pages with MkDocs Material.
• Content Coverage: Quickstart guides, configuration references, API documentation for ProxyAdapter, RateLimiter, TelemetryServer, and CLI usage manual.

---

Phase 2: Standalone Binaries and Containerized Images (Milestone 1.1)

Phase 2 broadens reach to users who require standalone execution or container orchestration.

1. Cross-Platform Standalone Binaries

• Compilation Tool: Utilize PyInstaller or Nuitka to compile self-contained executables bundling the Python runtime and dependencies.
• Target Architectures:
  • reliadl-windows-amd64.exe (Windows x86_64)
  • reliadl-linux-amd64 (Linux x86_64)
  • reliadl-darwin-arm64 (macOS Apple Silicon)
  • reliadl-darwin-amd64 (macOS Intel)
• Distribution: Attach pre-compiled, compressed binaries directly to GitHub Release assets.

2. Container Images (GHCR & Docker Hub)

• Registry Location: ghcr.io/pxa-labs/reliadl and docker.io/pxalabs/reliadl.
• Base Image: Multi-stage builds targeting Minimal Alpine or Distroless images to keep container size under 50 MB.
• Security & Privileges: Enforce non-root execution (USER 1000:1000) and expose default telemetry port 9090 for Prometheus scraping.

---

Phase 3: System Package Managers and Ecosystem Integrations (Milestone 1.2+)

Phase 3 lowers installation friction for desktop CLI power users via platform-native package managers.

1. Homebrew Formula (macOS & Linux)

• Repository: Maintain a tap PxA-Labs/homebrew-tap or submit to homebrew-core.
• Command: brew install pxa-labs/tap/reliadl.

2. Windows Package Managers (WinGet & Scoop)

• WinGet: Submit manifest to microsoft/winget-pkgs for winget install PxA-Labs.ReliaDL.
• Scoop: Maintain a custom bucket manifest for lightweight Windows installation.

3. Linux Package Formats (DEB / RPM / Snap / Flatpak)

• Use nfpm in CI pipelines to automatically construct .deb (Debian/Ubuntu) and .rpm (RHEL/Fedora) packages attached to releases.

---

4. Automated CI/CD Publishing Pipeline Architecture

The automated publishing pipeline will be executed via GitHub Actions triggered strictly by tag pushes (refs/tags/v*).

Git Tag Push (v1.0.0)
  |
  +---> Matrix Build & Unit / Integration Tests
  |
  +---> PyPI Build & OIDC Trusted Publish (pip wheel)
  |
  +---> Binary Cross-Compilation (PyInstaller for Win/Linux/macOS)
  |
  +---> Docker Multi-Arch Build & Push (GHCR ghcr.io/pxa-labs/reliadl)
  |
  +---> Sign Artifacts & Generate Attestations (Sigstore / Cosign)
  |
  +---> Create GitHub Release with Draft Changelog & Hashes

---

5. Security, Provenance, and Supply Chain Protection

To adhere to modern supply chain security standards:

1. GitHub Artifact Attestations: Generate build provenance attestations for all PyPI packages and GitHub Release binaries.
2. Cryptographic Signatures: Sign all binary assets with Sigstore / Cosign.
3. Software Bill of Materials (SBOM): Generate SPDX and CycloneDX SBOM manifests using syft and attach them to every release.
4. Vulnerability Scanning: Continuous automated checks via Dependabot and CodeQL static security analysis.

---

6. Channel Comparison and Maintenance Trade-off Matrix

Channel	Target User Reach	Setup Complexity	Maintenance Overhead	Priority Level
PyPI	High (Python Ecosystem)	Low	Low	Priority 1 (Phase 1)
GitHub Releases	High (All Developers)	Low	Low	Priority 1 (Phase 1)
Documentation Site	Critical	Medium	Low	Priority 1 (Phase 1)
Standalone Binaries	Medium (Non-Python CLI)	Medium	Medium	Priority 2 (Phase 2)
Docker / GHCR	Medium (Server / SRE)	Medium	Low	Priority 2 (Phase 2)
Homebrew / WinGet	High (Desktop CLI)	High	High	Priority 3 (Phase 3)

---

7. Open Discussion and Feedback Request

We welcome input from the community and maintainers on the following key points:

1. Phase 1 Timing: Are there any additional configuration requirements or CLI options needed before cutting the v1.0.0 release on PyPI?
2. Binary Compilation Preference: Should PyInstaller or Nuitka be preferred for standalone executable builds regarding startup speed and size?
3. Telemetry Container Setup: Does the proposed Docker image configuration meet standards for production Prometheus monitoring deployments?

Please share your thoughts, suggestions, and feedback in the comments below.

[purvanshjoshi]

Implementation Tracking Issues Created

To operationalize the multi-phase distribution RFC, dedicated tracking issues have been opened for each publishing channel and milestone:

Phase 1: Core Foundation (Priority 1)

• PyPI Package & OIDC Trusted Publisher Pipeline: Issue #84
• MkDocs Technical Documentation & GitHub Pages: Issue #85

Phase 2: Standalone & Containerized Distribution (Priority 2)

• Cross-Platform Standalone CLI Executables: Issue #86
• Multi-Architecture Docker Containers & GHCR: Issue #87

Phase 3: System Package Managers (Priority 3)

• System Package Managers (Homebrew, WinGet, Linux Packages): Issue #88

Each issue contains specific technical requirements, acceptance criteria, CI/CD pipeline steps, and security/provenance guidelines. Cross-references between Discussion #83 and each issue have been established.