imagecache

package
v2.0.0-dev.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package imagecache serves an upstream's images from the app's own origin, checked and kept in a bounded on-disk cache.

The app supplies a Fetch that calls its upstream client with its own credential, and checks a request's id against its library before calling Cache.Serve. The package makes no HTTP request and holds no credential.

An image is kept only when its declared type is image/jpeg, image/png, image/gif or image/webp, equals what net/http.DetectContentType sniffs from its bytes, and its size is 1 byte to Options.MaxImage. SVG is never kept. Anything else is dropped and answered image_unavailable.

Eviction

Options.MaxBytes bounds the total size of the cache's files on disk. After each image is written, the images fetched longest ago are removed until the total fits, so the directory exceeds MaxBytes by at most the one image being written. Serving an image does not change its place; refetching it does. An image whose file alone is larger than MaxBytes is answered and not kept.

Restart

Each file holds its key, type, digest and the time it was fetched, so New rebuilds the cache from the directory with no index file. It keeps every file that still passes the checks under the current options, and removes a 64-hex-digit-named file that does not, along with temp files over a minute old left by an interrupted write. Every other name is the app's. The fetch time is the one recorded in the file, so a restart changes no image's age. If MaxBytes was lowered, the oldest are evicted. Use one Cache per directory.

Orphans

An orphan is a cache file left on disk that the cache does not vouch for: one the start or Serve could not read, or one whose removal failed. It is never served and is outside MaxBytes. Forget of its key and any ForgetSpace remove it, and a new write of its key replaces it. A restart reads it again, so a removal error from Forget or ForgetSpace means a forgotten image may still be served after a restart: retry the call. The error ForgetSpace returns for a space over 128 bytes comes after its removals and does not go away on retry.

Shutdown

Cache.Shutdown cancels every fetch in flight, including background refetches of stale images, and waits for them. Call it from the server's teardown, after the drain and before closing Options.Root. After it, Serve still answers kept images, answers a miss image_unavailable, and never calls Fetch.

Fetch budget

A fetch runs under the first caller's deadline, or 30 seconds when its request has none. A background refetch always gets 30 seconds. Callers of one key share one fetch; the fetch is cancelled when every caller has left.

Example
package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"os"
	"strings"

	"github.com/cplieger/go/httpserver/v2/imagecache"
)

func main() {
	dir, err := os.MkdirTemp("", "covers")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(dir)
	root, err := os.OpenRoot(dir)
	if err != nil {
		panic(err)
	}
	defer root.Close()

	// The app's Fetch calls its upstream client with its own credential.
	fetch := func(ctx context.Context, k imagecache.Key) (imagecache.Image, bool, error) {
		png := "\x89PNG\r\n\x1a\n" + strings.Repeat("\x00", 64)
		return imagecache.Image{Type: "image/png", Data: []byte(png)}, true, nil
	}
	covers, err := imagecache.New(imagecache.Options{Root: root, Fetch: fetch})
	if err != nil {
		panic(err)
	}
	defer func() { _ = covers.Shutdown(context.Background()) }()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /covers/{id}", func(w http.ResponseWriter, r *http.Request) {
		// The app checks the id against its own library before Serve.
		covers.Serve(w, r, imagecache.Key{Space: "radarr-1", ID: r.PathValue("id"), File: "poster-250.jpg"})
	})

	rec := httptest.NewRecorder()
	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/covers/42", http.NoBody))
	fmt.Println(rec.Code, rec.Header().Get("Content-Type"), rec.Header().Get("Cache-Control"))
}
Output:
200 image/png private, max-age=86400

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CodeSpecs

func CodeSpecs() map[httpserver.ErrorCode]httpserver.CodeSpec

CodeSpecs returns the codes Serve answers, with their status and remediation, for the app's own code table. The map is the caller's copy.

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache serves upstream images from a bounded on-disk cache. Its methods are safe for concurrent use.

func New

func New(o Options) (*Cache, error)

New returns a Cache over o.Root, keeping the images a previous Cache left there (see the package doc). It fails on a nil Root or Fetch, an option outside its range, or a root it cannot list.

func (*Cache) Forget

func (c *Cache) Forget(k Key) error

Forget drops k's kept image and any fetch of it in flight, so the next Serve of k fetches anew, and removes k's file whether or not it is kept. An error means the file may still be on disk, where a restart can serve it again; retry the call. A key never kept is not an error.

func (*Cache) ForgetSpace

func (c *Cache) ForgetSpace(space string) error

ForgetSpace is Forget for every key whose Space is space, joining each removal's error, with Forget's meaning. It also removes every orphan (see the package doc), since an orphan's space is unknown, and fails a space over 128 bytes once those removals are done.

func (*Cache) Serve

func (c *Cache) Serve(w http.ResponseWriter, r *http.Request, k Key)

Serve answers k's image: a kept one at once (refetching it in the background once older than Refresh), else one fetched under r's context, with callers of one key sharing one fetch. A 200 carries the image's type, a strong ETag and Cache-Control: private, max-age=86400, and a matching If-None-Match answers 304. Errors go through Options.Errors: image_not_found 404 when the upstream has no such image or a key part is over 128 bytes, image_unavailable 503 with Retry-After: 60 when it cannot give one now and nothing is kept.

func (*Cache) Shutdown

func (c *Cache) Shutdown(ctx context.Context) error

Shutdown cancels every fetch the Cache runs, foreground and background, and waits for each to return, or for ctx to end, answering ctx.Err(). After it, Serve answers kept images without refetching and a miss with image_unavailable, never calling Fetch. Call it before closing Root. It is safe to call more than once.

type Fetch

type Fetch func(ctx context.Context, k Key) (img Image, found bool, err error)

Fetch is the app's upstream call for k. found false with a nil error means the upstream has no such image; img is then ignored. A non-nil error wins over found.

type Image

type Image struct {
	Type string
	Data []byte
}

Image is what the upstream answered: its declared media type and bytes.

type Key

type Key struct{ Space, ID, File string }

Key names one upstream image, built from the app's stored ids only. Each part is at most 128 bytes; Serve answers image_not_found for a longer one.

type Options

type Options struct {
	// Root is the cache directory; the Cache owns every 64-hex-digit file
	// name in it, one Cache per directory. The caller closes it after
	// Shutdown.
	Root  *os.Root
	Fetch Fetch
	// Errors writes Serve's error answers; nil means httpserver.WriteError.
	Errors httpserver.ErrorResponder
	// Logger nil means slog.Default() at the time of each line.
	Logger *slog.Logger
	// MaxImage is the largest image kept: 64 KiB to 16 MiB, default 2 MiB.
	MaxImage int64
	// MaxBytes bounds the cache's files on disk: 1 MiB to 4 GiB, default
	// 256 MiB.
	MaxBytes int64
	// Refresh is the age past which a kept image is refetched in the
	// background: 1 hour to 30 days, default 7 days.
	Refresh time.Duration
	// Fetches bounds the Fetch calls in flight across the cache: 1 to 16,
	// default 4.
	Fetches int
}

Options configures New. A zero numeric field takes its default; any other value outside its range makes New fail.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL