3日間のクールダウンとは、`lodash`がバージョン`4.18.0`を公開しても、3日間が経過するまでビルドは`4.17.21`を使い続けることを意味します。新しいリリースが侵害されていたとしても、あなたは決して露出されません。

解決順序: パッケージのオーバーライド、次にエコシステムのオーバーライド、最後にグローバルデフォルトです。これにより、保守的なデフォルトを設定しつつ、より迅速な更新が必要なパッケージには例外を設けることができます。完全な設定リファレンスについては、[docs/configuration.md](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md)を参照してください。

## 対応レジストリ

| レジストリ | 言語/プラットフォーム | クールダウン | 完了 |
|----------|-------------------|:--------:|:---------:|
| npm | JavaScript | あり | ✓ |
| Cargo | Rust | あり | ✓ |
| RubyGems | Ruby | あり | ✓ |
| Go proxy | Go | | ✓ |
| Hex | Elixir | あり* | ✓ |
| pub.dev | Dart | あり | ✓ |
| PyPI | Python | あり | ✓ |
| Maven | Java | | ✓ |
| Gradle Build Cache | Java/Kotlin | | ✓ |
| NuGet | .NET | あり | ✓ |
| Composer | PHP | あり | ✓ |
| Conan | C/C++ | | ✓ |
| Conda | Python/R | あり | ✓ |
| CRAN | R | | ✓ |
| Julia | Julia | | ✓ |
| Container | Docker/OCI | | ✓ |
| Debian | Debian/Ubuntu | | ✓ |
| RPM | RHEL/Fedora | | ✓ |
| Alpine | Alpine Linux | | ✗ |
| Arch | Arch Linux | | ✗ |
| Chef | Chef | | ✗ |
| Generic | 任意 | | ✗ |
| Helm | Kubernetes | | ✗ |
| Swift | Swift | | ✗ |
| Vagrant | Vagrant | | ✗ |

クールダウンには、メタデータ内の公開タイムスタンプが必要です。クールダウン列に「あり」がないレジストリは、タイムスタンプを公開していないか、まだ配線されていません。

\* Hexのクールダウンには、レジストリの署名検証を無効にする必要があります（`HEX_NO_VERIFY_REPO_ORIGIN=1`）。プロキシがprotobufペイロードを再エンコードするためです。

## インストール```bash
brew install git-pkgs/git-pkgs/proxy

プロキシが起動しました。パッケージマネージャーがそれを使用するように設定してください。

## OpenAPI（Swagger）

このリポジトリはswaggoを使用して、注釈付きハンドラーからOpenAPI仕様を生成します。

仕様を生成するには：```bash
go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

`.npmrc` でプロジェクトごとに設定することもできます:```
registry=http://localhost:8080/npm/

### Cargo

`~/.cargo/config.toml` を作成または編集します:```toml
[source.crates-io]
replace-with = "proxy"

[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

Or configure globally:```bash
gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

Or in your shell profile for persistence.

### Hex (Elixir)

Configure in `~/.hex/hex.config`:```erlang
{default_url, <<"http://localhost:8080/hex">>}.

### pub.dev (Dart/Flutter)

`PUB_HOSTED_URL` 環境変数を設定します:```bash
export PUB_HOSTED_URL=http://localhost:8080/pub

Or set in `~/.pip/pip.conf`:```ini
[global]
index-url = http://localhost:8080/pypi/simple/

`/maven/` エンドポイントは、プライマリのアップストリームとして Maven Central を使用し、プライマリのアップストリームが not found を返した場合には、Gradle Plugin Portal を Gradle プラグインのマーカーメタデータおよび関連アーティファクトのフォールバックとして使用します。

同じプロキシエンドポイントを介した Gradle プラグインの解決については、以下を参照してください。```kotlin
pluginManagement {
  repositories {
    maven(url = "http://localhost:8080/maven/")
  }
}

### NuGet

`nuget.config` で設定します:```xml
<configuration>
  <packageSources>
    <clear />
    <add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
  </packageSources>
</configuration>

### Composer (PHP)

`composer.json` で設定します:```json
{
    "repositories": [
        {
            "type": "composer",
            "url": "http://localhost:8080/composer"
        }
    ]
}

### Conan (C/C++)

プロキシをリモートとして追加します:```bash
conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter

またはコマンドで設定します:```bash
conda config --add channels http://localhost:8080/conda/main

~/.Rprofile` に記述して永続化することもできます:```r
local({
  r <- getOption("repos")
  r["CRAN"] <- "http://localhost:8080/cran"
  options(repos = r)
})

Or inside a running session:

実行中のセッション内で:```julia
ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()

Docker を再起動します:```bash
sudo systemctl restart docker

### Helm

各HTTPチャートリポジトリに名前を付けて設定し、対応するプロキシURLをHelmに追加します。```yaml
upstream:
  helm:
    bitnami: "https://charts.bitnami.com/bitnami"

プロキシは通常のメタデータキャッシュ設定を使用して`index.yaml`をキャッシュし、インデックスからSHA-256ダイジェストを検証した後にチャートアーカイブをキャッシュします。

OCIレジストリに保存されているチャートの場合、名前付きOCIアップストリームを設定し、チャート参照に予約済みの`upstream/{name}`プレフィックスを追加します。```yaml
upstream:
  oci:
    ghcr: "https://ghcr.io"

### Debian / APT

`/etc/apt/sources.list.d/proxy.list` でプロキシを使用するように APT を設定します:```
deb http://localhost:8080/debian stable main contrib

The upstream defaults to `http://deb.debian.org/debian`. To proxy a different APT repository (e.g. Ubuntu), set `upstream.debian` in the config file or `PROXY_UPSTREAM_DEBIAN` in the environment:

上流のデフォルトは `http://deb.debian.org/debian` です。別のAPTリポジトリ（例：Ubuntu）をプロキシするには、設定ファイルで `upstream.debian` を設定するか、環境変数で `PROXY_UPSTREAM_DEBIAN` を設定します：```yaml
upstream:
  debian: "http://archive.ubuntu.com/ubuntu"

Then:```bash
sudo dnf clean all
sudo dnf update

### 環境変数```bash
PROXY_LISTEN=:8080
PROXY_BASE_URL=http://localhost:8080
PROXY_UI_URL=http://localhost:8080  # Optional; defaults to PROXY_BASE_URL
PROXY_STORAGE_URL=file:///var/cache/proxy/artifacts
PROXY_DATABASE_DRIVER=sqlite
PROXY_DATABASE_PATH=./cache/proxy.db
PROXY_DATABASE_URL=postgres://user:pass@localhost/proxy?sslmode=disable
PROXY_LOG_LEVEL=info
PROXY_LOG_FORMAT=text
PROXY_ACCESS_LOG_PATH=/var/log/proxy/access.jsonl

[設定リファレンス](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md#upstream-registries)で、すべてのアップストリームキー、環境変数、デフォルトURLを確認してください。

設定ファイルで実行:```bash
./proxy -config /etc/proxy/config.yaml

または環境変数を使用する場合:```bash
PROXY_DATABASE_DRIVER=postgres
PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable

For S3互換サービス（MinIOなど）の場合：```yaml
storage:
  url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"

認証には[アプリケーションのデフォルト資格情報](https://docs.cloud.google.com/docs/authentication/application-default-credentials)を使用します。つまり、設定や環境に資格情報を埋め込む必要はありません。サポートされるソースは、優先順に次のとおりです。

- **GKE Workload Identity** — プロキシを実行するKubernetesサービスアカウントを、バケットに対して`roles/storage.objectAdmin`を持つGoogleサービスアカウントにバインドします。プロキシはワークロードのトークンを自動的に使用します。
- GCE、Cloud Run、Cloud Functionsなどでの**アタッチされたサービスアカウント**。
- サービスアカウントのJSONキーファイルを指す**`GOOGLE_APPLICATION_CREDENTIALS`**環境変数。
- ローカル開発用の**`gcloud auth application-default login`**。

#### GKE Workload Identityのセットアップ```bash
# 1. Create a Google service account
gcloud iam service-accounts create git-pkgs-proxy \
  --project=PROJECT_ID

# 2. Grant it access to the bucket
gsutil iam ch \
  serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin \
  gs://my-bucket-name

# 3. Bind the Kubernetes service account to it
gcloud iam service-accounts add-iam-policy-binding \
  git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

# 4. Annotate the Kubernetes service account
kubectl annotate serviceaccount KSA_NAME \
  --namespace=NAMESPACE \
  iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com

## CLI コマンド

### serve (デフォルト)

プロキシサーバーを起動します。コマンドが指定されていない場合のデフォルトコマンドです。```bash
proxy serve [flags]
proxy [flags]  # same as 'proxy serve'

ミラーコマンドは、`serve`と同じストレージおよびデータベースフラグを受け入れます。すでにキャッシュされたアーティファクトはスキップされます。

サーバーが実行中の場合は、ミラーAPIも利用できます。```bash
# Start a mirror job
curl -X POST http://localhost:8080/api/mirror \
  -H "Content-Type: application/json" \
  -d '{"purls": ["pkg:npm/[email protected]"]}'

# Check job status
curl http://localhost:8080/api/mirror/mirror-1

# Cancel a running job
curl -X DELETE http://localhost:8080/api/mirror/mirror-1

例出力:```
Cache Statistics
================

Packages:   45
Versions:   128
Artifacts:  128
Total size: 892.4 MB
Total hits: 1547

Packages by ecosystem:
  npm        32
  cargo      13

Most popular packages:
   1. npm/lodash (342 hits, 24.7 KB)
   2. npm/react (198 hits, 89.3 KB)
   3. cargo/serde (156 hits, 234.1 KB)

Recently cached:
  npm/[email protected] (2024-01-15 14:32, 54.2 KB)
  cargo/[email protected] (2024-01-15 14:28, 412.8 KB)

The `-p` flag is used to specify the port number, and the `-t` flag is used to specify the target IP address. The `-m` flag is used to specify the mode, which can be `tcp`, `udp`, or `icmp`. The `-f` flag is used to specify the output file name. The `-v` flag is used to enable verbose output. The `-h` flag is used to display the help menu.```json
{
  "ecosystem": "npm",
  "name": "lodash",
  "latest_version": "4.17.21",
  "license": "MIT",
  "license_category": "permissive",
  "description": "Lodash modular utilities",
  "homepage": "https://lodash.com/",
  "repository": "https://github.com/lodash/lodash",
  "registry_url": "https://registry.npmjs.org"
}

The `-p` flag is used to specify the port number, and the `-h` flag is used to specify the hostname or IP address. The `-t` flag is used to specify the timeout value in seconds. The `-v` flag is used to enable verbose output. The `-q` flag is used to specify the number of queries to send. The `-r` flag is used to specify the number of retries. The `-w` flag is used to specify the wait time between queries. The `-s` flag is used to specify the source IP address. The `-d` flag is used to specify the destination IP address. The `-c` flag is used to specify the number of packets to send. The `-i` flag is used to specify the interval between packets. The `-o` flag is used to specify the output file. The `-e` flag is used to specify the error file. The `-a` flag is used to specify the authentication method. The `-u` flag is used to specify the username. The `-p` flag is used to specify the password. The `-k` flag is used to specify the key file. The `-l` flag is used to specify the log file. The `-m` flag is used to specify the mode. The `-n` flag is used to specify the number of threads. The `-x` flag is used to specify the proxy. The `-y` flag is used to specify the proxy type. The `-z` flag is used to specify the proxy port. The `-A` flag is used to specify the user agent. The `-B` flag is used to specify the base URL. The `-C` flag is used to specify the cookie. The `-D` flag is used to specify the data. The `-E` flag is used to specify the encoding. The `-F` flag is used to specify the file. The `-G` flag is used to specify the GET request. The `-H` flag is used to specify the header. The `-I` flag is used to specify the HEAD request. The `-J` flag is used to specify the JSON data. The `-K` flag is used to specify the key. The `-L` flag is used to specify the location. The `-M` flag is used to specify the method. The `-N` flag is used to specify the name. The `-O` flag is used to specify the output. The `-P` flag is used to specify the path. The `-Q` flag is used to specify the query. The `-R` flag is used to specify the redirect. The `-S` flag is used to specify the status. The `-T` flag is used to specify the type. The `-U` flag is used to specify the URL. The `-V` flag is used to specify the version. The `-W` flag is used to specify the wordlist. The `-X` flag is used to specify the XML data. The `-Y` flag is used to specify the YAML data. The `-Z` flag is used to specify the zip file.```json
{
  "package": {
    "ecosystem": "npm",
    "name": "lodash",
    "latest_version": "4.17.21",
    "license": "MIT",
    "license_category": "permissive"
  },
  "version": {
    "ecosystem": "npm",
    "name": "lodash",
    "version": "4.17.0",
    "license": "MIT",
    "published_at": "2016-06-17T03:59:56Z",
    "yanked": false,
    "is_outdated": true
  },
  "vulnerabilities": [
    {
      "id": "GHSA-p6mc-m468-83gw",
      "summary": "Prototype Pollution in lodash",
      "severity": "HIGH",
      "cvss_score": 7.4,
      "fixed_version": "4.17.12"
    }
  ],
  "is_outdated": true,
  "license_category": "permissive"
}

The `-p` flag is used to specify the port number, and the `-t` flag is used to specify the target IP address. The `-m` flag is used to specify the mode, which can be `tcp`, `udp`, or `icmp`. The `-s` flag is used to specify the source IP address, and the `-d` flag is used to specify the destination IP address. The `-c` flag is used to specify the number of packets to send, and the `-i` flag is used to specify the interval between packets. The `-v` flag is used to enable verbose output, and the `-h` flag is used to display the help message.```json
{
  "results": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.0",
      "latest_version": "4.17.21",
      "is_outdated": true
    },
    {
      "ecosystem": "pypi",
      "name": "requests",
      "version": "2.25.0",
      "latest_version": "2.31.0",
      "is_outdated": true
    }
  ]
}

The `-p` flag is used to specify the port number, and the `-t` flag is used to specify the target IP address. The `-m` flag is used to specify the mode, which can be `tcp`, `udp`, or `icmp`. The `-f` flag is used to specify the output file name. The `-v` flag is used to enable verbose output. The `-h` flag is used to display the help menu.```json
{
  "packages": {
    "pkg:npm/lodash": {
      "ecosystem": "npm",
      "name": "lodash",
      "latest_version": "4.17.21",
      "license": "MIT",
      "license_category": "permissive"
    },
    "pkg:pypi/requests": {
      "ecosystem": "pypi",
      "name": "requests",
      "latest_version": "2.31.0",
      "license": "Apache-2.0",
      "license_category": "permissive"
    }
  }
}

## 動作の仕組み

1. パッケージマネージャーがプロキシにパッケージのメタデータを要求する
2. プロキシがアップストリームからメタデータを取得し、アーティファクトのURLをプロキシを指すように書き換える
3. パッケージマネージャーがアーティファクト（tarball、crateなど）を要求する
4. プロキシがローカルキャッシュを確認する：
   - **キャッシュヒット**: ローカルストレージから配信する
   - **キャッシュミス**: アップストリームから取得し、ローカルに保存してクライアントに配信する
5. 同じアーティファクトへの後続の要求はキャッシュから配信される```
┌─────────────┐     ┌─────────┐     ┌──────────┐
│   npm/cargo │────▶│  proxy  │────▶│ upstream │
│   client    │◀────│         │◀────│ registry │
└─────────────┘     └─────────┘     └──────────┘
                         │
                         ▼
                    ┌─────────┐
                    │  cache  │
                    │ storage │
                    └─────────┘

失敗したチェックには`"error"`フィールドが含まれます。ストレージの失敗には、どのプローブステップが失敗したかを示す`"step"`フィールド（`write`、`size`、`read`、`verify`、`delete`）も含まれます。データベースチェックが失敗した場合、ストレージエントリは`{"status": "skipped"}`を報告するため、レスポンスには常に同じキーセットが含まれます。

ストレージプローブの結果は、リモートバックエンドのプローブコストを抑えるために、`health.storage_probe_interval`（デフォルト30秒）の間キャッシュされます。プローブは最大10秒間（ハードコードされたプローブごとのタイムアウト）内部ミューテックスを保持するため、`/health`はKubernetesの**readiness**プローブとして意図されており、livenessプローブではありません。遅いS3ラウンドトリップはポッドをローテーションから外すべきであり、再起動させるべきではありません。

Prometheus用のスクレイプ設定:```yaml
scrape_configs:
  - job_name: git-pkgs-proxy
    static_configs:
      - targets: ["localhost:8080"]

有効にして起動します：```bash
sudo systemctl enable proxy
sudo systemctl start proxy

Postgres と S3 を使用する場合:```bash
docker run -p 8080:8080 \
  -e PROXY_DATABASE_DRIVER=postgres \
  -e PROXY_DATABASE_URL=postgres://user:pass@db:5432/proxy \
  -e PROXY_STORAGE_URL=s3://my-bucket?region=us-east-1 \
  -e AWS_ACCESS_KEY_ID=... \
  -e AWS_SECRET_ACCESS_KEY=... \
  proxy

UI がパッケージエンドポイントとは異なるホスト名で到達される場合（たとえば、UI がパブリックにドメイン上で公開され、ビルドマシンが Docker ネットワークエイリアスにアクセスする場合）は、`ui_base_url` を個別に設定してください。`base_url` はパッケージマネージャーとメタデータ書き換えが使用する URL です。`ui_base_url` は Web UI を訪れる人間に表示される URL（canonical/`og:url` タグとインストールガイドのバナー）です。```yaml
base_url: "http://pkg-proxy:8080"        # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui"  # public UI URL

location /ui/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
}

location / {
    return 404;
}

Traefikの例では、`PathPrefix(/ui)`を使用して、パブリックルーターがUIトラフィックのみに一致するようにしています。```yaml
labels:
  traefik.enable: "true"
  traefik.http.services.pkg-proxy.loadbalancer.server.port: "8080"
  traefik.http.routers.pkg-proxy.rule: "Host(`proxy.example.com`) && PathPrefix(`/ui`)"
  traefik.http.routers.pkg-proxy.entrypoints: "websecure"

キャッシュメタデータはSQLite（デフォルト）またはPostgreSQLに保存されます。ローカルキャッシュをクリアするには：```bash
rm -rf ./cache/artifacts/*
rm ./cache/proxy.db

テストを実行:```bash
go test ./...