Metadata-Version: 2.4
Name: aria2-oci-pull
Version: 0.1.0
Summary: Resumable, parallel Docker/OCI image downloader powered by system aria2c
Author: aria2-oci-pull contributors
License-Expression: MIT
Keywords: docker,oci,registry,aria2,container,download,mirror
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.28
Requires-Dist: rich<16,>=13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# aria2-oci-pull

Download Docker/OCI images without a running Docker daemon, using the **system `aria2c`** for concurrent, resumable layer downloads, then export a tar archive compatible with `docker load`.

> **Status:** `0.1.0` (initial release candidate). The project is not affiliated with Docker, aria2 or any registry mirror provider. Package name availability on PyPI must be checked before uploading.

## Features

- Docker Registry HTTP API V2, Docker and OCI image manifests and multi-architecture indexes
- Automatic `linux/amd64` selection or `--platform linux/arm64`
- Multiple concurrent blobs and aria2 segmented transfers, resume via persistent `.aria2` state
- SHA-256 verification of downloaded blobs; cache reuse on later runs
- Bearer token / basic authentication (credentials via environment variables)
- Optional HTTP(S) proxy, custom Registry or Docker Hub proxy mirror
- Rich progress bars, transfer statistics, retries, large-layers-first scheduling
- `docker load -i image.tar` compatible tar archives (gzip or uncompressed layers)

## Requirements

- Linux with **`aria2c` on PATH** (not bundled in the Python wheel)
- Python 3.9+
- Enough storage for both downloaded blobs and **uncompressed** `layer.tar` files: image export may need substantially more space than its compressed size.
- Docker is only needed if you want to import or run the exported tar archive.

```bash
# Ubuntu/Debian
sudo apt update && sudo apt install -y aria2

# Once published to PyPI:
pip install aria2-oci-pull

# Before publishing, install from the source checkout:
pip install .

aria2-oci-pull --help
docker-pull-aria2 --version  # equivalent entry point
python -m aria2_oci_pull --help
```

## Examples

```bash
# Docker Hub (implicit library namespace)
aria2-oci-pull ubuntu:24.04

# Download from an alternative registry, keeping its own image name
aria2-oci-pull docker.1ms.run/library/ubuntu:24.04

# Download via a compatible Docker Hub mirror but keep the tag ubuntu:24.04
aria2-oci-pull ubuntu:24.04 --mirror docker.1ms.run

# Direct access to a third-party registry
aria2-oci-pull ghcr.io/owner/image:latest

# Example proxy: proxy traffic includes Registry metadata and aria2 blobs
aria2-oci-pull ubuntu:24.04 \
  --proxy http://127.0.0.1:7890 \
  --jobs 4 --connections 16 \
  --min-split-size 4M --low-speed-limit 64K \
  --cache-dir /data/docker-cache --keep-cache

# Select a different architecture or output path
aria2-oci-pull ubuntu:24.04 --platform linux/arm64 -o ubuntu_arm64.tar

# Import the final archive
docker load -i library_ubuntu_24.04.tar
```

The `--mirror` option **replaces only the Registry host**. It works when the mirror exposes the *same repository paths* through the Registry V2 API; it cannot translate arbitrary proprietary mirror URLs. When you instead write a registry in the image name, that complete name is what `docker load` will import.

### Resuming

Run the **same command again** after interruption. The cache directory retains verified blobs and aria2 `.aria2` control files. With `--keep-cache`, successful downloads also retain their cache for later reuse. Without it, the work directory is removed only after archive creation succeeds. Blob digests are always checked before reuse.

### Credentials and proxy

```bash
export DOCKER_USERNAME='your-username'
export DOCKER_PASSWORD='your-registry-token'
aria2-oci-pull private.example.org/team/image:v1

# Or keep a secret in a custom environment variable:
aria2-oci-pull private.example.org/team/image:v1 \
  --username your-username --password-env MY_REGISTRY_PASSWORD
```

The `--proxy` argument takes an **HTTP or HTTPS proxy endpoint** (e.g. `http://127.0.0.1:7890`), not an arbitrary SOCKS port. Otherwise `HTTPS_PROXY` / `HTTP_PROXY` are consulted. Do not put proxy passwords or access tokens on shared command lines or in screenshots. Registry authentication and TLS certificate verification are enabled by default; `--insecure` disables certificate verification and should only be used for controlled test registries.

### Performance tuning

- `-j / --jobs` controls concurrent blobs, default `3`.
- `-x / --connections` controls simultaneous connections per blob, default `16` (range 1–16).
- `--min-split-size` limits the splitting of small blobs.
- `--low-speed-limit 64K` asks aria2 to retry unusually slow connections (default `0`, disabled); a throttling CDN may become slower with aggressive retries.
- Large layers are queued before small layers to reduce final single-layer tail latency. It does not override CDN limits or guarantee greater bandwidth.

## Limitations

- Supports manifests with SHA-256 blob digests; **zstd layers are not yet supported**.
- Exports a **single chosen platform**, not a multi-platform archive.
- Does not build/push images and does not require or control the Docker daemon.
- Some registries need provider-specific authentication or artifact URLs that this client does not support.
- Long downloads are integration-dependent. Unit tests mock registry and aria2c; real-network tests should be run against a small image and with `docker load` before any production use.

## Development / release

```bash
python -m pip install -e '.[dev]'
python -m pytest -q
python -m build
python -m twine check dist/*

# Test release (separate TestPyPI account/token):
python -m twine upload --repository testpypi dist/*

# Official release, after verifying name, ownership and project metadata:
python -m twine upload dist/*
```

Alternatively, use GitHub Actions Trusted Publishing: configure a PyPI **pending publisher** for the repository, workflow filename `.github/workflows/publish.yml`, and `pypi` environment, and then dispatch that workflow. The OIDC route does not require a stored PyPI token. Never configure a repository or public release under somebody else's project name.

Before publishing, review the license/attribution of any code incorporated from other projects and update the `LICENSE`/author details with the actual ownership information.

## License

MIT; see [LICENSE](LICENSE).
