81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
---
|
||
title: Verdaccio prune semantics — proxied vs locally-published
|
||
type: concept
|
||
tags: [verdaccio, npm, storage, gc, gotcha]
|
||
sources: []
|
||
updated: 2026-05-21
|
||
---
|
||
|
||
# Verdaccio prune — proxied vs locally-published
|
||
|
||
Прежде чем удалять `.tgz` из verdaccio storage, надо отличать proxied (cached from upstream — безопасно удалить, можно re-fetch) от locally-published (authoritative copy — удаление = permanent loss).
|
||
|
||
## Storage layout
|
||
|
||
`/storage/data/<package>/`:
|
||
- `package.json` — packument (metadata, дешёвый)
|
||
- `<package>-<version>.tgz` — binary tarballs (дорогие)
|
||
|
||
Для scoped: `/storage/data/<scope>/<package>/...`. Scope в filename `.tgz` **НЕ** включается — `@snollajs/snolla/snolla-0.2.4.tgz`.
|
||
|
||
## Detection rule
|
||
|
||
В `package.json` есть три relevant fields:
|
||
|
||
```yaml
|
||
_uplinks: { npmjs: { etag, fetched } } # upstream registries verdaccio queried
|
||
_distfiles: { "<pkg>-<v>.tgz": { url, sha, registry } } # ключи — ИМЯ tarball, не version
|
||
_attachments: { "<pkg>-<v>.tgz": { shasum } } # cached + locally-uploaded tarballs
|
||
```
|
||
|
||
**Detection**:
|
||
- `_distfiles[<tgzName>]` defined → **proxied**, tarball mirrored from upstream URL. Удалять `.tgz` файл безопасно — verdaccio re-fetch'нет при следующем `npm install pkg@v`.
|
||
- `_distfiles[<tgzName>]` undefined, but `_attachments[<tgzName>]` defined и `.tgz` есть на диске → **locally-published** (`npm publish` в verdaccio через `verdaccio` registry). **НЕ удалять** — это единственная копия.
|
||
|
||
## Gotcha: keying
|
||
|
||
Ключи `_distfiles` — это **filename** (`lodash-0.1.0.tgz`), **НЕ** version string (`0.1.0`). Lookup `_distfiles["0.1.0"]` всегда возвращает undefined, ложно классифицируя ВСЕ versions как locally-published.
|
||
|
||
Easy mistake: первый draft prune скрипта проверял `_distfiles[v]` → dry-run показал 4597/7021 packages "защищены" (на самом деле ВСЕ proxied lodash/react/etc). Fix: `_distfiles[<tgzBase>-<v>.tgz]` где `tgzBase = name.replace(/^@[^/]+\//, '')` (strip scope для filename).
|
||
|
||
## Safe prune algorithm
|
||
|
||
```
|
||
для каждого package:
|
||
keepSet = dist-tagged versions # {latest, next, beta, ...}
|
||
others = versions − keepSet, отсортированные по time[v] desc
|
||
keepSet += first (N - |keepSet|) из others # N = 10
|
||
для v в (versions − keepSet):
|
||
tgzName = "<scope-stripped-name>-<v>.tgz"
|
||
if _distfiles[tgzName] undefined:
|
||
continue # locally-published, skip
|
||
if .tgz file exists: delete file
|
||
if _attachments[tgzName] exists: delete entry
|
||
если что-то изменили в _attachments:
|
||
bump _rev (`<num+1>-<random_hex>`)
|
||
atomic rewrite package.json (tmp + rename)
|
||
```
|
||
|
||
## Atomic write + _rev
|
||
|
||
`package.json` rewrite через `fs.writeFileSync(tmp); fs.renameSync(tmp, real)` — atomic on POSIX same-fs. Race window между «file gone» и «package.json updated» ничтожен.
|
||
|
||
`_rev` field в формате `<num>-<hash>` (CouchDB-style). Verdaccio проверяет его для optimistic concurrency. Bump = increment number + new random hex. Это invalidates npm client packument cache.
|
||
|
||
Дополнительная подстраховка от race: **stop verdaccio перед prune, start после** (~1 min downtime weekly). Альтернатива — atomic rewrite без stop — допустима, но cache invalidation менее clean.
|
||
|
||
## Что НЕ трогать
|
||
|
||
- `versions{}` и `time{}` — оставляем metadata in-place даже после удаления tarballs. Для proxied packages npm re-fetch'нет tgz при request; metadata лёгкая (~KB).
|
||
- `_uplinks{}` — agent-level state о fetch timestamps; не относится к individual versions.
|
||
- `readme`, `users`, `_id` — irrelevant для prune.
|
||
|
||
## Применено
|
||
|
||
[`vds-gc-cron`](../../.tasks/vds-gc-cron.md) — weekly cron Sun 03:30 MSK на VDS. Smoke 2026-05-21: 8.5G→6.8G freed, 4524 tgz deleted, 73 locally-published versions защищены (`@snollajs/*` + ~40 другие internal packages).
|
||
|
||
## Ссылки
|
||
|
||
- Verdaccio local-storage docs: https://verdaccio.org/docs/configuration#storage
|
||
- Algorithm в репо: `/opt/stacks/gc/scripts/verdaccio-prune.js` на VDS.
|