Skip to content

Latest commit

 

History

History
107 lines (80 loc) · 3.63 KB

README.md

File metadata and controls

107 lines (80 loc) · 3.63 KB
Raw

Caching HTTP proxy server for the crates.io registry

Introduction

crates-io-proxy implements transparent caching for both the sparse registry index at https://index.crates.io/ and the static crate file download server.

Two independent HTTP proxy endpoints are implemented:

  1. Listens to HTTP GET requests at /index/.../{crate}, forwards them to https://index.crates.io/ and caches the downloaded registry index entries as JSON text files on the local filesystem.

  2. Listens to HTTP GET requests at /api/v1/crates/{crate}/{version}/download, forwards them to https://crates.io/ and caches the downloaded crates as .crate files on the local filesystem.

Subsequent sparse registry index and crate download API hits are serviced using the locally cached index entry and crate files.

As a convenience feature, the download requests for the config.json file found at the sparse index root are served with a replacement file, which changes the crate download URL to point to this same proxy server.

Usage

Cargo can be told to use the crate registry mirror by using the source replacement feature. Add the following lines to your .cargo/config:

[source.crates-io]
replace-with = "crates-io-mirror"

[registries.crates-io-mirror]
index = "sparse+http://crates-io-proxy.example.com:3080/index/"

Using static git index mirror

crates-io-proxy can also be used as the crate file download proxy server with a separate git-based registry index.

To use this configuration, clone and rehost the crates.io index repository from GitHub and change "dl" parameter in config.json file in the repository root to point to the crates-io-proxy server instead:

{
    "dl": "https://crates-io-proxy.example.com:3080/api/v1/crates",
    "api": "https://crates.io"
}

In this configuration, the git registry index link should be used instead:

[registries.crates-io-mirror]
index = "https://crates-io-index.example.com/crates-io-index.git"

Configuration

The proxy server can be configured by either command line options or environment variables.

Run crates-io-proxy --help to get the following help page:

Usage:
    crates-io-proxy [options]

Options:
    -v, --verbose              print more debug info
    -h, --help                 print help and exit
    -V, --version              print version and exit
    -L, --listen ADDRESS:PORT  address and port to listen at (0.0.0.0:3080)
        --listen-unix PATH     Unix domain socket path to listen at
    -U, --upstream-url URL     upstream download URL (https://crates.io/)
    -I, --index-url URL        upstream index URL (https://index.crates.io/)
    -S, --proxy-url URL        this proxy server URL (http://localhost:3080/)
    -C, --cache-dir DIR        proxy cache directory (/var/cache/crates-io-proxy)
    -T, --cache-ttl SECONDS    index cache entry Time-to-Live in seconds (3600)

Environment:
    INDEX_CRATES_IO_URL        same as --index-url option
    CRATES_IO_URL              same as --upstream-url option
    CRATES_IO_PROXY_URL        same as --proxy-url option
    CRATES_IO_PROXY_CACHE_DIR  same as --cache-dir option
    CRATES_IO_PROXY_CACHE_TTL  same as --cache-ttl option

Advanced configuration

By default, crates-io-proxy uses embedded TLS trusted root certificates. It is possible to configure it to use the system certificate store at the build time by setting the native-certs feature flag.

Configuring this behavior at the run time is not supported yet.