nordisk/holger

Cross-repo search — guide

Class: guide · Function: search. What the feature is and how to drive it. The why lives in search-design.md; the gentle version in search-for-idiots.md.

Holger can find an artifact across every configured repository at once, by name, coordinate, content checksum, or raw archive path. Three doors, one engine.

CLI

# By name (case-insensitive substring), across all repos in the config:
holger-server search --config holger.ron --name serde

# By GAVC-style coordinate (Maven groupId + artifactId + version):
holger-server search --config holger.ron --namespace org.example --name widget --version 2.3.4

# By content checksum (sha256 hex) — finds the coordinate whose bytes hash to it:
holger-server search --config holger.ron --checksum a7f1987ea82e...bfb1

# By raw archive path substring (yields path hits):
holger-server search --config holger.ron --path .jar

# Scope to specific repos, cap the hit count:
holger-server search --config holger.ron --name serde --repo rust-dev --repo rust-prod --limit 50

--namespace accepts --group as an alias; --checksum accepts --sha256. A bare search --config holger.ron lists every artifact (bounded by --limit).

Sample output:

search: 2 artifact hit(s), 0 path hit(s)
  [rust-dev] -/serde@1.0.1 (11 bytes)
  [rust-dev] -/serde@1.0.0 (11 bytes)

gRPC

SearchService.Search(SearchRequest) -> SearchResponse — a normal read RPC (anonymous, no auth), served on the same endpoint as the other services.

SearchRequest { name, namespace, version, checksum, path, repositories[], limit }
SearchResponse {
  artifacts[] { repository, id{namespace,name,version}, size_bytes, content_type, checksum }
  paths[]     { repository, path }
  truncated
}

Empty string = "axis not set". checksum on a hit is populated only when the request supplied a checksum.

HTTP (read-only door)

GET /-/search?name=serde&namespace=org.example&version=1.0.0&checksum=<hex>&path=<sub>&repo=<a>&repo=<b>&limit=100

Returns the engine's SearchResults as JSON:

{"artifacts":[{"repository":"rust-dev","id":{"namespace":null,"name":"serde","version":"1.0.1"},
  "size_bytes":11,"content_type":"application/octet-stream","checksum":null}],
  "paths":[],"truncated":false}

Reserved under /-/ so it never collides with a repository route. Read-only — there is no HTTP write/search-index mutation. Query keys: name, namespace (alias group), version, checksum (alias sha256), path, repo/ repository (repeatable), limit.

Semantics you can rely on

• All supplied axes are AND-ed.
• name / namespace — case-insensitive substring. version — exact.
• A namespace query never matches a namespace-less artifact (e.g. a Rust crate).
• checksum reads + hashes candidate bytes (the one expensive axis) — leave it empty unless you are searching by digest.
• path searches raw archive paths and yields paths[], independent of the artifact axes.
• truncated = the hit cap was reached and more matches exist — raise --limit.
• A repository whose backend errors is skipped (logged), never a hard failure.