Spegel

https://github.com/spegel-org/spegel
Admin
Spegel is a stateless cluster local OCI registry mirror that locally caches images to improve pull...
Tokens:117,806
Snippets:869
Trust Score:8.3
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create registry and serve HTTP

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Usage example for creating a registry with options and starting an HTTP server. It shows how to configure filters, resolve retries, timeout, userinfo, and OCI client, then serve the registry handler.

```go
reg, err := registry.NewRegistry(ctrd, router,
	registry.WithRegistryFilters(filters),
	registry.WithResolveRetries(args.MirrorResolveRetries),
	registry.WithResolveTimeout(args.MirrorResolveTimeout),
	registry.WithUserinfo(userinfo),
	registry.WithOCIClient(ociClient))
if err != nil {
	return err
}
srv := &http.Server{
	Addr:    args.RegistryAddr,
	Handler: reg.Handler(log),
}
err := srv.ListenAndServe()
```

--------------------------------

### Usage example (registry command wiring)

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-containerd.md

Example of using containerd.NewContainerd and containerd.AddMirrorConfiguration functions.

```APIDOC
## Usage example (registry command wiring)

### Description
Example of wiring the containerd client and mirror configuration in a registry command.

### Code Example
```go
ctrd, err := containerd.NewContainerd(ctx, args.ContainerdSock, args.ContainerdNamespace,
	containerd.WithContentPath(args.ContainerdContentPath),
	containerd.WithFilters(filters))
if err != nil {
	return err
}
defer ctrd.Close()

// Mirror configuration out-of-band:
err = containerd.AddMirrorConfiguration(ctx, "/etc/containerd/certs.d",
	args.MirroredRegistries, args.MirrorTargets,
	args.ResolveTags, args.PrependExisting, userinfo)
if err != nil {
	return err
}
```
```

--------------------------------

### Usage examples for Provider and Watcher

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/store.md

Usage examples showing how the registry consumes the Provider and how sync consumes the Watcher.

```go
// Registry consumes the provider:
ok := true
if dist.Digest == "" {
	_, err := provider.Resolve(req.Context(), dist.Identifier())
	ok = err == nil
} else {
	_, err = provider.Descriptor(req.Context(), dist.Digest)
	ok = err == nil
}
if !ok {
	r.mirrorHandler(req.Context(), dist, rw)
}
```

```go
// Sync consumes the watcher (see routing.Sync):
events, eventCh, err := watcher.Watch(ctx)
if err != nil {
	return err
}
```

--------------------------------

### Usage example for cleanup.Run and cleanup.Wait

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/cleanup.md

Usage example showing how to call cleanup.Run and cleanup.Wait. Run performs the cleanup, and Wait blocks until all nodes have finished cleanup.

```go
// Cleanup command:
err := cleanup.Run(ctx, args.Addr, args.ContainerdRegistryConfigPath)
if err != nil {
	return err
}

// In a separate deployment step, block until all nodes finished cleanup:
err = cleanup.Wait(ctx, args.ProbeEndpoint, args.Period, args.Threshold)
if err != nil {
	return err
}
```

--------------------------------

### Example: calling Client.Fetch with mirror and userinfo

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-client.md

A Go example that calls Client.Fetch with a mirror and userinfo options, handles the error, and defers closing the response body. The returned descriptor is used for content metadata.

```go
rc, desc, err := client.Fetch(ctx, dist, oci.WithFetchMirror(mirror), oci.WithFetchUserinfo(userinfo))
if err != nil {
	return err
}
defer httpx.DrainAndClose(rc)
```

--------------------------------

### Client.Pull example usage

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-client.md

Example call to Client.Pull with a mirror and platform option. Logs an error if the pull fails.

```go
err := client.Pull(ctx, img, &writer, oci.WithPullMirror(mirror), oci.WithPullPlatform(platforms.DefaultSpec()))
if err != nil {
	log.Error(err, "pull failed")
}
```

--------------------------------

### NewClient constructor and usage example

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-client.md

Creates a new OCI client with the given options. The example shows using WithDisableKeepAlives to disable keep-alives.

```go
func NewClient(opts ...ClientOption) (*Client, error)
```

```go
client, err := oci.NewClient(oci.WithDisableKeepAlives(true))
if err != nil {
	return err
}
```

--------------------------------

### GET /readyz

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/endpoints.md

Readiness probe for the registry server.

```APIDOC
## GET /readyz

### Description
Readiness probe that reports whether the libp2p router is ready.

### Method
GET

### Endpoint
/readyz

### Parameters
None

### Response
#### Success Response (200)
- No body

#### Error Response (500)
- Body: `"could not determine router readiness: <err>"`

```

--------------------------------

### GET /readyz

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/endpoints.md

Documentation for the cleanup probe server's readiness endpoint.

```APIDOC
## GET /readyz

### Description
This endpoint is used by cleanup-wait probes to check the readiness of the cleanup probe server. It returns a 200 status code only when the HTTP method is GET and the path is exactly `/readyz`. Any other request method or path results in a 404 response with a log message "unsupported probe request".

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- No specific response body is documented.

#### Error Response (404)
- Returned for any request that is not a GET to `/readyz`.

### Notes
- This endpoint is part of the cleanup probe server, configured via the `--addr` flag.
- It is used by `cleanup-wait` probes.
```

--------------------------------

### Usage example of option.Apply

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/internal.md

Shows how to use option.Apply with a RegistryConfig, setting ResolveRetries and ResolveTimeout, and handling the returned error.

```go
cfg := RegistryConfig{
	ResolveRetries: 3,
	ResolveTimeout: 20 * time.Millisecond,
}
err := option.Apply(&cfg, opts...)
if err != nil {
	return nil, err
}
```

--------------------------------

### Set up httpx ServeMux and client

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-core.md

Creates a new ServeMux, registers GET handlers for /readyz and /v2/, then configures an HTTP client with a custom transport and TLS client config. Use this to wire up the server and client sides together.

```go
mux := httpx.NewServeMux(log)
mux.HandleFunc("GET /readyz", r.readyHandler)
mux.HandleFunc("GET /v2/", r.registryHandler)

// Client-side:
client := httpx.BaseClient()
transport := httpx.BaseTransport()
transport.TLSClientConfig = tlsCfg
client.Transport = transport
```

--------------------------------

### (r *Router) Run

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Starts the router's main loop.

```APIDOC
## (r *Router) Run

### Description
Runs the router loop: waits for connectivity, bootstraps peers, re-bootstraps every 30 minutes, and cleans up on context cancellation.

### Signature
```go
func (r *Router) Run(ctx context.Context) error
```

### Parameters
- **ctx** (context.Context) - Required - Cancellation context.

### Returns
- error

### Behavior
1. Waits for connectivity (`connectivityGate.WaitFor(true)`), then `resilient.Retry(ctx, 0, BackoffDelay(50ms, 10s), ...)` running `bootstrapPeers`; retries stop on context cancel or after connectivity is confirmed (the retry body returns success when `connectivityGate.State()` is false). Failures are logged via `WithOnRetry`; on final failure logs `"could not run bootstrap"` and loops again.
2. Re-bootstraps every 30 minutes.
3. On context done, closes `prov`, `kdht`, and `host` in order, joining all close errors.
```

--------------------------------

### Usage example: register and expose metrics

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/metrics.md

Shows how to call `metrics.Register()` and set up an HTTP handler for `/metrics` using `promhttp.HandlerFor` with `metrics.DefaultGatherer`.

```go
metrics.Register()
mux := http.NewServeMux()
mux.Handle("/metrics", promhttp.HandlerFor(metrics.DefaultGatherer, promhttp.HandlerOpts{}))
```

--------------------------------

### Use preflight.Check in main.go

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/preflight.md

Usage example showing how to load version info and run the preflight check in main.go. The returned error is a plain formatted error with no custom type or error codes; consumers propagate or log it.

```go
// main.go registryCommand
versionInfo, err := version.Load()
if err != nil {
	return err
}
err = preflight.Check(versionInfo)
if err != nil {
	log.Error(err, "preflight check failed")
	return err
}
```

--------------------------------

### Initialize and run libp2p router with static bootstrapper

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Use this snippet to set up a libp2p router with a static bootstrapper. It creates the bootstrapper from a comma-separated list of peer addresses, then constructs a router with the given address, bootstrapper, and registry port. The router is started in a new goroutine via the provided error group.

```go
bootstrapper, err := libp2p.NewStaticBootstrapperFromStrings(args.StaticBootstrapPeers)
if err != nil {
	return err
}
router, err := libp2p.NewRouter(ctx, args.RouterAddr, bootstrapper, registryPort,
	libp2p.WithDataDir(args.DataDir))
if err != nil {
	return err
}
group.Go(func(ctx context.Context) error {
	return router.Run(ctx)
})
```

--------------------------------

### readyHandler

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Handles GET /readyz, returning 200 when the router is ready and 500 on error.

```APIDOC
## readyHandler

### Description
Handles GET /readyz, returning 200 when the router is ready and 500 on error.

### Method
GET

### Endpoint
/readyz

### Response
- **200** - When `r.router.Ready(req.Context())` is true and the router did not error.
- **500** - With `"could not determine router readiness: %w"` on error.
```

--------------------------------

### Handler method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Registers routes on an httpx.NewServeMux(log) for /readyz, /livez, and /v2/ (GET and HEAD).

```go
func (r *Registry) Handler(log logr.Logger) *httpx.ServeMux
```

--------------------------------

### readyHandler method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Handles GET /readyz. Returns 200 when r.router.Ready(req.Context()) is true and the router did not error; 500 with "could not determine router readiness: %w" on error.

```go
func (r *Registry) readyHandler(rw httpx.ResponseWriter, req *http.Request)
```

--------------------------------

### livenessHandler method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Handles GET /livez and always returns 200.

```go
func (r *Registry) livenessHandler(rw httpx.ResponseWriter, req *http.Request)
```

--------------------------------

### Bootstrap bearer token with certs using httpx.LoadCerts

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Use this snippet to load certificates from a directory and create an HTTP bootstrapper for a libp2p node. It returns an error if certificate loading fails. The example initializes a bootstrapper with the loaded certificate pool and the configured bootstrap URL.

```go
// Bearer token bootstrap with certs:
pool, cert, err := httpx.LoadCerts(cfg.HTTPBootstrapCertDir)
if err != nil {
	return nil, err
}
bootstrapper, err := libp2p.NewHTTPBootstrapper(cfg.HTTPBootstrapURL, pool, cert)
```

--------------------------------

### Package store types and interfaces

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/types.md

Defines the core types and interfaces for the package store, including Descriptor, Event, Provider, and Watcher. The Provider interface requires methods for resolving references, getting descriptors, and opening content. The Watcher interface returns a list of events and a channel for streaming events.

```go
type Descriptor struct {
	MediaType string `json:"mediaType"`
	Digest digest.Digest `json:"digest"`
	Size int64 `json:"size"`
}

type EventType string
// CreateEvent = "CREATE", DeleteEvent = "DELETE"

type Event struct {
	Type EventType
	Reference string
	Digest digest.Digest
}

type Provider interface {
	Name() string
	Resolve(ctx context.Context, ref string) (digest.Digest, error)
	Descriptor(ctx context.Context, dgst digest.Digest) (Descriptor, error)
	Open(ctx context.Context, dgst digest.Digest) (io.ReadSeekCloser, error)
}

type Watcher interface {
	Watch(ctx context.Context) ([]Event, <-chan Event, error)
}
```

--------------------------------

### MemoryRouter type and methods

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing.md

Defines the MemoryRouter struct and its methods for an in-memory Router implementation used in tests and embedding. NewMemoryRouter starts ready, SetReadiness toggles readiness, Lookup returns an exhausted iterator when empty, Advertise registers self for each key, Withdraw removes it, and Get returns peers under read lock.

```go
var _ Router = &MemoryRouter{}

type MemoryRouter struct {
	resolver map[string][]Peer
	self     Peer
	ready    atomic.Bool
	mx       sync.RWMutex
}

func NewMemoryRouter(resolver map[string][]Peer, self Peer) *MemoryRouter
func (m *MemoryRouter) SetReadiness(ready bool)
func (m *MemoryRouter) Ready(ctx context.Context) (bool, error)
func (m *MemoryRouter) Lookup(ctx context.Context, key string, count int) (*Iterator, error)
func (m *MemoryRouter) Advertise(ctx context.Context, keys []string) error
func (m *MemoryRouter) Withdraw(ctx context.Context, keys []string) error
func (m *MemoryRouter) Add(key string, peer Peer)
func (m *MemoryRouter) Delete(key string, peer Peer)
func (m *MemoryRouter) Get(key string) ([]Peer, bool)
```

--------------------------------

### Get kubeconfig and access cluster

Source: https://github.com/spegel-org/spegel/blob/main/CONTRIBUTING.md

After running the integration tests, get a kubeconfig file to access the cluster for debugging. Use 'kind get clusters' to find the cluster name.

```shell
kind get clusters
```

```shell
kind get kubeconfig --name <cluster-name> > kubeconfig
```

```shell
export KUBECONFIG=$(pwd)/kubeconfig
```

```shell
kubectl -n spegel get pods
```

--------------------------------

### GET /v2

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/endpoints.md

Indicates OCI v2 support.

```APIDOC
## GET /v2

### Description
Indicates OCI v2 support.

### Method
GET

### Endpoint
/v2

### Parameters
None

### Response
#### Success Response (200)
- No body

```

--------------------------------

### GET /livez

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/endpoints.md

Liveness probe for the registry server.

```APIDOC
## GET /livez

### Description
Liveness probe that always returns 200.

### Method
GET

### Endpoint
/livez

### Parameters
None

### Response
#### Success Response (200)
- No body

```

--------------------------------

### NewWeb constructor

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Creates a new Web instance. Loads templates with helper functions and prepends missingkey=error behavior on render.

```go
func NewWeb(router *libp2p.Router, imgLister oci.ImageLister, reg *registry.Registry, mirror *url.URL, opts ...WebOption) (*Web, error)
```

--------------------------------

### livenessHandler

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Handles GET /livez, always returning 200.

```APIDOC
## livenessHandler

### Description
Handles GET /livez, always returning 200.

### Method
GET

### Endpoint
/livez

### Response
- **200** - Always returns 200.
```

--------------------------------

### Registry command wiring with containerd.NewContainerd and AddMirrorConfiguration

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-containerd.md

Shows how to wire the registry command: create a containerd client with content path and filters, then add mirror configuration out-of-band using AddMirrorConfiguration with the specified arguments. Both calls return errors that should be handled.

```go
ctrd, err := containerd.NewContainerd(ctx, args.ContainerdSock, args.ContainerdNamespace,
	containerd.WithContentPath(args.ContainerdContentPath),
	containerd.WithFilters(filters))
if err != nil {
	return err
}
defer ctrd.Close()

// Mirror configuration out-of-band:
err = containerd.AddMirrorConfiguration(ctx, "/etc/containerd/certs.d",
	args.MirroredRegistries, args.MirrorTargets,
	args.ResolveTags, args.PrependExisting, userinfo)
if err != nil {
	return err
}
```

--------------------------------

### Check

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/preflight.md

Performs a startup sanity check to ensure the runtime environment is supported. Returns nil if the environment is supported, otherwise an error.

```APIDOC
## Check

### Description
Performs a startup sanity check to ensure the runtime environment is supported. Returns nil if the environment is supported, otherwise an error.

### Method
N/A (Go function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **versionInfo** (version.Info) - Required - Runtime and version information struct from `version.Load()`. Relevant fields: `versionInfo.Runtime.OS` and `versionInfo.Runtime.Distro`.

### Request Example
```go
versionInfo, err := version.Load()
if err != nil {
	return err
}
err = preflight.Check(versionInfo)
if err != nil {
	log.Error(err, "preflight check failed")
	return err
}
```

### Response
#### Success Response (nil)
- Returns `nil` when the environment is supported.

#### Error Response
- Returns an `error` formatted as `"unsupported container distro %s"` with the distro name when the environment is not supported.

### Error Handling
- The returned error is a plain formatted `error`; it is not a custom type and carries no error codes.
- There is no way to bypass the check at runtime other than the environment conditions described in the source.
```

--------------------------------

### Router Run method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Runs the router loop, waiting for connectivity, bootstrapping peers, re-bootstrapping every 30 minutes, and cleaning up on context cancellation.

```go
func (r *Router) Run(ctx context.Context) error
```

--------------------------------

### ContentRange struct

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Represents a content range header with start, end, and size fields.

```go
// ContentRange represents a content range header.
type ContentRange struct {
	Start int64
	End   int64
	Size  int64
}
```

--------------------------------

### Run

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/cleanup.md

Restores the pre-Spegel containerd registry configuration and serves a readiness probe on the given address. Returns the first error from the errgroup.

```APIDOC
## Run

### Description
Restores the pre-Spegel containerd registry configuration and serves a readiness probe on the given address. Returns the first error from the errgroup.

### Method
N/A (Go function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **ctx** (context.Context) - Required - Signal/cancellation context.
- **addr** (string) - Required - Address to serve the readiness probe on (`--addr`, e.g. `:8080`).
- **configPath** (string) - Required - Containerd hosts config directory (`--containerd-registry-config-path`).

### Request Example
```go
// Cleanup command:
err := cleanup.Run(ctx, args.Addr, args.ContainerdRegistryConfigPath)
if err != nil {
	return err
}
```

### Response
#### Success Response (200)
- **error** (error) - Returns nil on success, or the first error from the errgroup.

#### Response Example
```go
// No response body; returns error or nil.
```

### Error Handling
- Returns the first error from the errgroup.
- If the readiness probe receives a non-GET request or a path other than `/readyz`, it logs `"unsupported probe request"` and returns 404.
- If the context is cancelled, the server shuts down within a 30s timeout.
```

--------------------------------

### Call preflight.Check in registryCommand

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/preflight.md

Invoked once in registryCommand (main.go) right after version.Load() and before services are constructed. Returns an error if the environment is unsupported.

```go
err = preflight.Check(versionInfo)
if err != nil {
	return err
}
```

--------------------------------

### ContentRange.Length

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Returns the byte size of the content within the range, calculated as End - Start + 1.

```APIDOC
## ContentRange.Length

### Description
Returns the byte size of the content within the range. This should not be confused with size which is the total size of the content.

### Method Signature
go
func (crng ContentRange) Length() int64


### Parameters
- **crng** (ContentRange) - The content range.

### Returns
- **int64** - The length of the content within the range, calculated as `End - Start + 1`.

### Example
go
// Example usage
length := crng.Length()

```

--------------------------------

### ContentRange.String

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Formats a ContentRange as a header value string, e.g., `bytes {Start}-{End}/{Size}`.

```APIDOC
## ContentRange.String

### Description
Returns the content range content as a formatted header value string.

### Method Signature
go
func (crng ContentRange) String() string


### Parameters
- **crng** (ContentRange) - The content range to format.

### Returns
- **string** - The formatted header value, e.g., `bytes {Start}-{End}/{Size}`.

### Example
go
// Example usage
str := crng.String()

```

--------------------------------

### Get

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing.md

Returns the list of peers for a given key and a boolean indicating if the key was found. It reads under the read lock.

```APIDOC
## Get

### Description
Returns the list of peers for a given key and a boolean indicating if the key was found. It reads under the read lock.

### Function Signature
```go
func (m *MemoryRouter) Get(key string) ([]Peer, bool)
```

### Parameters
- **key** (string) - Required - The key to look up.

### Returns
- **[]Peer** - The list of peers associated with the key.
- **bool** - True if the key was found, false otherwise.
```

--------------------------------

### Handler method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Returns a ServeMux that registers the /debug/web/* routes.

```go
func (w *Web) Handler(log logr.Logger) *httpx.ServeMux
```

--------------------------------

### Router Ready method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Returns true when the DHT routing table is non-empty and connectivity is established.

```go
func (r *Router) Ready(ctx context.Context) (bool, error)
```

--------------------------------

### GET /metrics

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/metrics.md

The /metrics endpoint exposes Prometheus metrics for the Spegel application. It is served using promhttp.HandlerFor with the DefaultGatherer.

```APIDOC
## [GET] /metrics

### Description
Exposes Prometheus metrics for the Spegel application. Metrics are registered via the `metrics.Register()` function and served using `promhttp.HandlerFor`.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- Prometheus metrics in text format

#### Response Example
```
# HELP spegel_mirror_requests_total Total number of mirror requests.
# TYPE spegel_mirror_requests_total counter
spegel_mirror_requests_total{registry="...",cache="hit"} 10
```
```

--------------------------------

### NewWeb

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Creates a new Web instance with the provided router, image lister, registry, mirror URL, and optional configuration. Loads embedded templates and prepares the debug web interface.

```APIDOC
## NewWeb

### Description
Creates a new Web instance for the debug web interface. It takes the router, image lister, registry, mirror URL, and optional OCI client configuration, and loads embedded templates.

### Method
NewWeb

### Signature
func NewWeb(router *libp2p.Router, imgLister oci.ImageLister, reg *registry.Registry, mirror *url.URL, opts ...WebOption) (*Web, error)

### Parameters
- **router** (*libp2p.Router) - Required - Peers, local addresses, measure.
- **imgLister** (oci.ImageLister) - Required - Local image listing (`containerd.Containerd`).
- **reg** (*registry.Registry) - Required - Mirror statistics.
- **mirror** (*url.URL) - Required - Mirror URL used for pull timing.
- **opts** (...WebOption) - Optional - `WithOCIClient`.

### Returns
- **web** (*Web) - The created Web instance.
- **error** (error) - Error if template loading fails.

```

--------------------------------

### Range.Validate

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Validates the content of a Range struct, ensuring start and end values are within acceptable bounds and not contradictory.

```APIDOC
## Range.Validate

### Description
Validates the content of a Range struct. Returns an error if the range is invalid.

### Method Signature
go
func (rng Range) Validate() error


### Parameters
- **rng** (Range) - The range to validate.

### Returns
- **error** - An error if validation fails. Possible errors: `"suffix range %d cannot be less than one"`, `"start range %d cannot be less than zero"`, `"end range %d cannot be less than zero"`, `"start %d cannot be larger than end %d"`, `"start and end range cannot both be empty"`.

### Example
go
// Example usage
rng := httpx.Range{Start: &start, End: &end}
err := rng.Validate()
if err != nil {
    // handle error
}

```

--------------------------------

### NewMemoryRouter

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing.md

Creates a new MemoryRouter with the given resolver map and self peer. The router starts in a ready state.

```APIDOC
## NewMemoryRouter

### Description
Creates a new in-memory Router with the provided resolver map and self peer. The router starts in a ready state.

### Function Signature
```go
func NewMemoryRouter(resolver map[string][]Peer, self Peer) *MemoryRouter
```

### Parameters
- **resolver** (map[string][]Peer) - Required - Initial mapping of keys to peer lists.
- **self** (Peer) - Required - The peer representing this router instance.

### Returns
- **\*MemoryRouter** - A pointer to the newly created MemoryRouter.
```

--------------------------------

### NewRouter constructor

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Constructs a new Router with the given context, listen address, bootstrapper, registry port, and options. Returns the router and an error.

```go
func NewRouter(ctx context.Context, addr string, bs Bootstrapper, registryPortStr string, opts ...RouterOption) (*Router, error)
```

--------------------------------

### OCI Helpers Usage Examples

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-helpers.md

Code snippets demonstrating the usage of the OCI helper functions: FilterForMirroredRegistries, RegexFilter, and FingerprintMediaType.

```APIDOC
## FilterForMirroredRegistries

### Description
Creates a filter that only allows mirroring of a whitelist of registries. Returns an error if the filter cannot be created.

### Function Signature
`func FilterForMirroredRegistries(registries []string) (*Filter, error)`

### Parameters
- **registries** ([]string) - Required - List of registry hostnames to whitelist for mirroring.

### Returns
- **filter** (*Filter) - A filter object to be used in the filter list, or nil if no filter is needed.
- **error** (error) - An error if the filter creation fails.

### Usage Example
```go
filter, err := oci.FilterForMirroredRegistries(args.MirroredRegistries)
if err != nil {
	return err
}
```
```

```APIDOC
## RegexFilter

### Description
A filter that matches registry names against a regular expression. Used to include or exclude registries from mirroring.

### Type Definition
`type RegexFilter struct { Regex string }`

### Fields
- **Regex** (string) - Required - The regular expression pattern to match against registry names.

### Usage Example
```go
filters := []oci.Filter{}
for _, r := range args.RegistryFilters {
	filters = append(filters, oci.RegexFilter{Regex: r})
}
```
```

```APIDOC
## FingerprintMediaType

### Description
Fingerprints a stream to determine its media type. Returns the media type string and an error if fingerprinting fails.

### Function Signature
`func FingerprintMediaType(rc io.Reader) (string, error)`

### Parameters
- **rc** (io.Reader) - Required - The stream to fingerprint.

### Returns
- **mediaType** (string) - The detected media type of the stream.
- **error** (error) - An error if fingerprinting fails.

### Usage Example
```go
mt, err := oci.FingerprintMediaType(rc)
if err != nil {
	log.Error(err, "could not fingerprint media type")
}
```
```

--------------------------------

### ContentRangeFromRange

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Constructs a ContentRange from a given Range and content size, normalizing start and end based on the size and verifying bounds.

```APIDOC
## ContentRangeFromRange

### Description
Returns a content range from a given range and content size. Start and end are normalized based on the given size and verified to be within bounds.

### Function Signature
go
func ContentRangeFromRange(rng Range, size int64) (ContentRange, error)


### Parameters
- **rng** (Range) - The range to convert.
- **size** (int64) - The total content size.

### Returns
- **ContentRange** - The normalized content range.
- **error** - An error if the range is invalid or out of bounds. Possible errors: `"size %d cannot be equal or less than zero"`, range validation errors, `"start %d is out of bounds for size %d"` when `Start >= size`.

### Example
go
// Example usage
crng, err := httpx.ContentRangeFromRange(rng, size)
if err != nil {
    // handle error
}

```

--------------------------------

### WithLibP2POptions function signature

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Returns a RouterOption that appends raw go-libp2p host options to the internal defaults.

```go
func WithLibP2POptions(opts ...libp2p.Option) RouterOption
```

--------------------------------

### GET /debug/web/metadata

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Returns JSON metadata about the local libp2p peer, including its ID. Responds with 500 on marshal or write failure.

```APIDOC
## GET /debug/web/metadata

### Description
Returns JSON metadata about the local libp2p peer, including its ID. Responds with 500 on marshal or write failure.

### Method
GET

### Endpoint
/debug/web/metadata

### Response
#### Success Response (200)
- **libp2p** (object) - Contains peer ID.
  - **id** (string) - The peer ID.

#### Response Example
{
  "libp2p": {
    "id": "<peer-id>"
  }
}

#### Error Response (500)
- Description: Internal server error on marshal or write failure.

```

--------------------------------

### userinfo.go — basic auth constants and function signatures

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Defines filename constants for username and password files, and declares three functions: LoadUserinfo loads credentials from a directory, UserinfoHeaderValue builds the Basic authorization header value, and AuthenticateUserinfo verifies credentials using constant-time comparison. LoadUserinfo returns nil when both files are missing, url.User for username only, and url.UserPassword when both are present. AuthenticateUserinfo returns false when the callback reports failure or on mismatch.

```go
const (
	UsernameFilename = "username"
	PasswordFilename = "password"
)

// LoadUserinfo loads a username and password file from the given base directory.
func LoadUserinfo(dirPath string) (*url.Userinfo, error)

// UserinfoHeaderValue returns the authorization header value for basic auth.
func UserinfoHeaderValue(userinfo url.Userinfo) string

// AuthenticateUserinfo returns true if the username and password from basic auth matches the user info.
func AuthenticateUserinfo(basicAuthFn func() (string, string, bool), userinfo url.Userinfo) bool
```

--------------------------------

### Implement preflight.Check logic

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/preflight.md

Exact logic of the preflight check. Returns nil if not in Kubernetes or if the runtime is linux with distro Distroless; otherwise returns an error with the unsupported distro.

```go
func Check(versionInfo version.Info) error {
	if os.Getenv(KubernetesEnvVar) == "" {
		return nil
	}
	if versionInfo.Runtime.OS == "linux" && versionInfo.Runtime.Distro == "Distroless" {
		return nil
	}
	return fmt.Errorf("unsupported container distro %s", versionInfo.Runtime.Distro)
}
```

--------------------------------

### Range struct

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-content.md

Represents a range header with optional start and end pointers to support parsing without known content size.

```go
// Range represents a range header.
// Both start and end are optional to support parsing without known content size.
type Range struct {
	Start *int64 `json:"start"`
	End   *int64 `json:"end"`
}
```

--------------------------------

### indexHandler method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Renders the index.html template.

```go
func (w *Web) indexHandler(rw httpx.ResponseWriter, req *http.Request)
```

--------------------------------

### Register function signature

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/metrics.md

Declares the `Register()` function that must-registers all Spegel metrics plus `httpx.RegisterMetrics` on `DefaultRegisterer`. Called once at the start of `registryCommand` in `main.go`.

```go
func Register()
```

--------------------------------

### GET /debug/web/stats

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Renders the stats page with local addresses, images, peers, and mirror last success duration. Returns 500 on any collection error.

```APIDOC
## GET /debug/web/stats

### Description
Renders the stats page with local addresses, images, peers, and mirror last success duration. Returns 500 on any collection error.

### Method
GET

### Endpoint
/debug/web/stats

### Response
#### Success Response (200)
- HTML page rendered from stats.html template.

#### Error Response (500)
- Description: Internal server error if any data collection fails.

```

--------------------------------

### WithUserinfo function signature

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Returns a `RegistryOption` that sets basic-auth credentials used both to protect this registry and to authenticate peer fetches.

```go
func WithUserinfo(userinfo *url.Userinfo) RegistryOption
```

--------------------------------

### DistributionPath struct in pkg/oci/distribution.go

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/types.md

Represents a distribution path with an embedded Reference, optional byte range (blobs only), scheme (http/https), method (GET or HEAD), and kind (manifests/blobs).

```go
type DistributionPath struct {
	Reference
	Range  *httpx.Range
	Scheme string
	Method string
	Kind   DistributionKind
}
```

--------------------------------

### NewRegistry constructor

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Constructs a Registry with a 32 KiB buffer pool (sync.Pool allocating []byte of 32*1024) and a hedger resilient.NewHedger([]float64{80, 85, 90}, 50*time.Millisecond). Requires a local content store (provider) and peer discovery router; optional RegistryOption builders.

```go
func NewRegistry(provider store.Provider, router routing.Router, opts ...RegistryOption) (*Registry, error)
```

--------------------------------

### GET /debug/web/measure

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/web.md

Measures mirror pull performance for a specified image. Requires an 'image' query parameter; returns 400 if missing or unparsable, 500 on measurement or pull errors.

```APIDOC
## GET /debug/web/measure

### Description
Measures mirror pull performance for a specified image. Requires an 'image' query parameter; returns 400 if missing or unparsable, 500 on measurement or pull errors.

### Method
GET

### Endpoint
/debug/web/measure

### Parameters
#### Query Parameters
- **image** (string) - Required - The image name to measure.

### Response
#### Success Response (200)
- HTML page rendered from measure.html template.

#### Error Response (400)
- Description: Bad request if image parameter is missing or unparsable.

#### Error Response (500)
- Description: Internal server error if measurement or pull fails.

```

--------------------------------

### StaticBootstrapper type and methods

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

StaticBootstrapper holds a fixed list of peers. NewStaticBootstrapperFromStrings parses each string with peer.AddrInfoFromString. Get returns a snapshot under the read lock; Add mutates under the write lock.

```go
type StaticBootstrapper struct {
	peers []peer.AddrInfo
	mx    sync.RWMutex
}

func NewStaticBootstrapperFromStrings(peerStrs []string) (*StaticBootstrapper, error)
func NewStaticBootstrapper(peers []peer.AddrInfo) *StaticBootstrapper
func (b *StaticBootstrapper) Get(ctx context.Context) ([]peer.AddrInfo, error)
func (b *StaticBootstrapper) Add(peer peer.AddrInfo)
```

--------------------------------

### WithRegistryFilters function signature

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/registry.md

Returns a `RegistryOption` that sets filters; matching request references receive a 404 response.

```go
func WithRegistryFilters(filters []oci.Filter) RegistryOption
```

--------------------------------

### Run linter and unit tests

Source: https://github.com/spegel-org/spegel/blob/main/CONTRIBUTING.md

Runs the linter and unit tests to quickly validate changes. Requires Go, golangci-lint, goreleaser, and Docker.

```shell
make lint test-unit
```

--------------------------------

### Bootstrapper interface

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Defines the Bootstrapper interface used to resolve peers for the P2P router. Get returns a list of peers; an empty peer ID is resolved, and a missing port defaults to the P2P router port.

```go
// Bootstrapper resolves peers to bootstrap with for the P2P router.
type Bootstrapper interface {
	// Get returns a list of peers that should be used as bootstrap nodes.
	// If the peer ID is empty it will be resolved.
	// If the address is missing a port the P2P router port will be used.
	Get(ctx context.Context) ([]peer.AddrInfo, error)
}
```

--------------------------------

### Ready

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing.md

Returns whether the MemoryRouter is ready. It checks the atomic readiness flag and returns nil error if ready, otherwise an error.

```APIDOC
## Ready

### Description
Returns whether the MemoryRouter is ready. It checks the atomic readiness flag and returns nil error if ready, otherwise an error.

### Function Signature
```go
func (m *MemoryRouter) Ready(ctx context.Context) (bool, error)
```

### Parameters
- **ctx** (context.Context) - Required - Context for the operation.

### Returns
- **bool** - True if the router is ready, false otherwise.
- **error** - nil if ready, otherwise an error indicating not ready.
```

--------------------------------

### Router Host method

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Returns the underlying libp2p host.

```go
func (r *Router) Host() host.Host
```

--------------------------------

### WithFetchUserinfo function signature

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-client.md

Returns a FetchOption that sets the Authorization: Basic header using the provided userinfo. The userinfo parameter is optional and defaults to nil.

```go
func WithFetchUserinfo(userinfo *url.Userinfo) FetchOption
```

--------------------------------

### HTTPBootstrapper type and methods

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

HTTPBootstrapper resolves bootstrap peers over HTTP. GETs the endpoint, requires 200, unmarshals a JSON array of BootstrapPeerAddrInfo, caps at 3 entries, and converts with FromBootstrapPeerAddrInfos. Uses TLS 1.2+ when pool and cert are provided.

```go
// HTTPBootstrapper resolves bootstrap peers over HTTP.
type HTTPBootstrapper struct {
	httpClient *http.Client
	endpoint   string
}

// NewHTTPBootstrapper creates an HTTP bootstrapper.
func NewHTTPBootstrapper(bootstrapURL url.URL, pool *x509.CertPool, cert *tls.Certificate) (*HTTPBootstrapper, error)
func (bs *HTTPBootstrapper) Get(ctx context.Context) ([]peer.AddrInfo, error)
```

--------------------------------

### Error handling and defaults with AllowDefaults and AllowTagOnly

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-image.md

Tag-only references are rejected unless AllowTagOnly is supplied. With AllowDefaults, registry defaults to docker.io, namespace to library, and tag to latest. On error, logs the error and returns it.

```go
// Tag-only references are rejected unless AllowTagOnly is supplied.
img, err := oci.ParseImage("nginx", oci.AllowDefaults(), oci.AllowTagOnly())
if err != nil {
	log.Error(err, "could not parse image")
	return err
}
// With AllowDefaults, registry defaults to docker.io, namespace to library, tag to latest.
```

--------------------------------

### Mirror Configuration Functions

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/oci-containerd.md

Documentation for the mirror configuration functions AddMirrorConfiguration and CleanupMirrorConfiguration.

```APIDOC
## AddMirrorConfiguration

### Description
Adds mirror configuration for containerd hosts. It creates host configuration files for specified registries, backing up the existing configuration first.

### Function Signature
```go
func AddMirrorConfiguration(ctx context.Context, configPath string, mirroredRegistries, mirrorTargets []string, resolveTags, prependExisting bool, userinfo *url.Userinfo) error
```

### Parameters
- **ctx** (context.Context) - Required - Logging/cancellation context.
- **configPath** (string) - Required - containerd hosts config dir (default `/etc/containerd/certs.d`).
- **mirroredRegistries** ([]string) - Required - Registries to create host config for; empty or `*`/`_default` = wildcard (all).
- **mirrorTargets** ([]string) - Required - Registries that act as mirrors (cannot be wildcard).
- **resolveTags** (bool) - Required - When true adds the `resolve` capability.
- **prependExisting** (bool) - Required - When true preserves pre-existing host entries.
- **userinfo** (*url.Userinfo) - Optional - Basic-auth header written into the host entries.

### Behavior
1. Validates registries using `oci.ParseRegistries`.
2. Backs up the config directory to `{configPath}/_backup` and clears the current config.
3. For each mirrored registry, renders a `hosts.toml` fragment with mirror targets, capabilities, and optional basic auth.
4. Writes the configuration to `{configPath}/{host}/hosts.toml`.

### Example Configuration Fragment
```toml
server = '<registry-url>'
[host.'<mirror-target>']
capabilities = ['pull' (, 'resolve')]
dial_timeout = '200ms'
[host.'<mirror-target>'.header]
Authorization = 'Basic ...'
```

### Notes
- `docker.io` is rewritten to `registry-1.docker.io`; wildcard registry renders no `server` line.
- When `prependExisting` is true, previous host entries are preserved and extra files are copied back.

## CleanupMirrorConfiguration

### Description
Restores the original configuration from the backup directory. If no backup exists, it logs a message and does nothing.

### Function Signature
```go
func CleanupMirrorConfiguration(ctx context.Context, configPath string) error
```

### Parameters
- **ctx** (context.Context) - Required - Logging/cancellation context.
- **configPath** (string) - Required - containerd hosts config dir.

### Behavior
- If `_backup` directory does not exist, logs `"skipping cleanup because backup directory does not exist"` and returns nil.
- Otherwise, clears the config directory, moves everything from `_backup` back, and removes `_backup`.
```

--------------------------------

### Go: Sync router with container daemon in main.go

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing.md

Use this snippet to start the routing synchronization loop in a goroutine. It calls routing.Sync with the router and container daemon, returning an error unless the context is canceled. The error is propagated to the group, which is typical for a main function using errgroup.

```go
// Wiring from main.go
group.Go(func(ctx context.Context) error {
	err := routing.Sync(ctx, router, ctrd)
	if err != nil && !errors.Is(err, context.Canceled) {
		return err
	}
	return nil
})
```

--------------------------------

### (r *Router) Ready

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/routing-libp2p.md

Checks if the router is ready.

```APIDOC
## (r *Router) Ready

### Description
Returns true when the DHT routing table is non-empty and connectivity is established.

### Signature
```go
func (r *Router) Ready(ctx context.Context) (bool, error)
```

### Parameters
- **ctx** (context.Context) - Required - Cancellation context.

### Returns
- (bool, error) - True when the DHT routing table is non-empty and connectivity is established (`!connectivityGate.State()`).
```

--------------------------------

### Containerd hosts.toml configuration for mirrored registries

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/configuration.md

Generated by the `configuration` subcommand for each mirrored registry at `{CONTAINERD_REGISTRY_CONFIG_PATH}/{registry-host}/hosts.toml`. The `server` line is omitted for wildcard registries, `capabilities` includes 'resolve' only when `--resolve-tags` is set, and the `Authorization` header is present only when a basic-auth secret is configured. The original config directory is backed up to `{configPath}/_backup` on first run and restored by the `cleanup` subcommand.

```toml
server = '<registry-url>'            # omitted for wildcard registry
[host.'<mirror-target>']
capabilities = ['pull', 'resolve']   # 'resolve' only when --resolve-tags
dial_timeout = '200ms'
[host.'<mirror-target>'.header]
Authorization = 'Basic ...'          # only when basic-auth secret present
```

--------------------------------

### ServeMux type and methods

Source: https://github.com/spegel-org/spegel/blob/main/_autodocs/api-reference/httpx-core.md

Defines the ServeMux struct, its constructor NewServeMux, and its methods ServeHTTP, Handle, and HandleFunc. NewServeMux takes a logger used for request logging and 404s. ServeHTTP wraps each request in a response and delegates to the stdlib mux, logging 'page not found' when no pattern matches. Handle wraps the handler in metrics and logging, skipping /readyz and /livez, and injects a logger into the request context.

```go
type ServeMux struct {
	mux *http.ServeMux
	log logr.Logger
}

func NewServeMux(log logr.Logger) *ServeMux
func (s *ServeMux) ServeHTTP(w http.ResponseWriter, req *http.Request)
func (s *ServeMux) Handle(pattern string, handler Handler)
func (s *ServeMux) HandleFunc(pattern string, handler func(rw ResponseWriter, req *http.Request))
```
Tokens:
Raw