config.example.yaml

# triplet configuration. The full surface lives here; everything is optional
# unless noted. Environment variable references such as `$VAR` and `${VAR}` are
# expanded before YAML parsing.

server:
  # Address the HTTP server binds to.
  listen: ":8080"
  read_timeout: 60s
  write_timeout: 5m
  # Public base URL the server is reachable at. Used to build canonical
  # `id` fields in info.json and Link headers. Required.
  public_base_url: "${TRIPLET_PUBLIC_BASE_URL}"

logging:
  # One of: debug, info, warn, error.
  level: info
  # One of: json, text.
  format: json
  # Triplet trusts X-Forwarded-For and X-Real-IP only when RemoteAddr is inside
  # one of these proxy CIDRs.
  trusted_proxy_cidrs:
  # - 10.0.0.0/8

metrics:
  # Exposes Prometheus metrics at /metrics on the main listener. Disabled by
  # default; enable only behind a scrape path that is not publicly reachable.
  enabled: false

debug:
  # pprof is mounted on the main listener and requires pprof_token when enabled.
  pprof_enabled: false
  pprof_prefix: /debug/pprof
  pprof_token: "${TRIPLET_PPROF_TOKEN}"

vips:
  # 0 lets libvips choose based on available cores.
  concurrency: 0
  # 0 disables the libvips operation cache. triplet's own derivative/source
  # caches are usually the right place to retain work across requests.
  cache_max_mem: 0
  cache_max_files: 0
  report_leaks: false
  # Recommended hardening flag from the libvips security review. Triplet keeps
  # the advertised image source/response formats unblocked while leaving unused
  # complex loaders blocked.
  block_untrusted: true
  # Optional libvips operation/class blocklist applied at startup before any
  # image processing. Names are libvips class names from `vips -l`; blocking a
  # class blocks subclasses too. Useful for disabling loaders you do not want
  # exposed even if the runtime libvips build supports them.
  blocked_operations:
    - VipsForeignLoadPdf

iiif:
  # Optional shared CORS allowlist for IIIF Presentation and Image unless
  # iiif.image.allowed_origins is set. Entries must be exact
  # origins (`https://viewer.example.edu`) or `*`.
  # When empty, no Access-Control-Allow-Origin header is emitted.
  # allowed_origins:
  #   - https://viewer.example.edu
  image:
    enabled: true
    # URL prefix the Image API is mounted at. The IIIF spec is agnostic;
    # `/iiif/3` is the convention used by most servers and viewers.
    prefix: /iiif/3
    # Optional Image API CORS override. Uses iiif.allowed_origins when empty.
    # allowed_origins:
    #   - https://viewer.example.edu
    # Refuse requests whose decoded output would exceed this many pixels.
    # Cheap protection against tile-bomb DoS.
    max_output_pixels: 100000000
    # Setting this to true is required before max_output_pixels can be left at
    # 0. Do not enable it for public HTTP deployments.
    allow_unsafe_unlimited_output_pixels: false
    # Refuse sources whose decoded width × height exceeds this many pixels.
    # 0 disables.
    max_source_pixels: 250000000
    # Refuse or stop spooling encoded source files larger than this many bytes
    # when the source is not already available as a file path. 0 disables.
    max_source_bytes: 1GiB
    # Per-request encoded response limit. Refuse one generated derivative if it
    # is larger than this many bytes after libvips export. This protects the
    # server from returning or caching a single unexpectedly huge response.
    # This is not the total cache size; see cache.max_bytes for the aggregate
    # filesystem derivative-cache budget. 0 disables.
    max_derivative_bytes: 512MiB
    # Bound concurrent libvips jobs across image derivatives and info probes.
    max_concurrent_transforms: 4
    # Advertise additional transform limits in info.json so clients can avoid
    # over-large requests up front. 0 omits the field.
    max_width: 0
    max_height: 0
    # `preserve` keeps embedded profiles without converting, matching common
    # Cantaloupe behavior. `normalize` converts to sRGB/gray. `none` skips
    # profile conversion and strips metadata where the output codec supports it.
    color_management: preserve
    # How libvips should read source pixels from disk or spooled source files.
    # `auto` is the production default: it uses random access for region crops
    # and sequential access for full-image or resize requests. Sequential access
    # streams forward and can reduce memory and I/O for whole-image reads, but it
    # is a poor fit for tile/region workloads that need pixels from arbitrary
    # offsets. Random access is better for crops and tiled viewers, but can do
    # unnecessary work for simple full-image derivatives. Force `sequential` or
    # `random` only when profiling a specific deployment or source format.
    load_access: auto
    # Cache info.json dimensions by identifier plus source mtime/size.
    info_dimension_cache: true
    # Optional protected route for invalidating all derivative variants for one
    # identifier: POST {prefix}/{identifier}/cache/invalidate with
    # Authorization: Bearer ${TRIPLET_IMAGE_CACHE_INVALIDATION_TOKEN}.
    # If TRIPLET_IMAGE_CACHE_INVALIDATION_TOKEN is unset,
    # TRIPLET_IMAGE_CACHE_INVALIDATION_TOKEN_FILE may point at a mounted secret
    # file whose contents populate the token environment variable.
    # Optionally restrict callers by client CIDR. When Triplet is behind a
    # proxy, configure logging.trusted_proxy_cidrs so X-Forwarded-For is trusted.
    # cache_invalidation_allowed_cidrs: [127.0.0.1/32, ::1/128]
    # cache_invalidation_token: ${TRIPLET_IMAGE_CACHE_INVALIDATION_TOKEN}
  presentation:
    enabled: false
    prefix: /presentation/v3
    # Configure exactly one backend: root for filesystem, or dsn for MariaDB.
    # Filesystem-backed presentation store. Manifests live at
    # {root}/{itemID}/manifest.json. Annotation pages live at
    # {root}/{itemID}/canvas/{canvasID}/annotations.json.
    root: ./testdata/presentation
    # dsn: scribe:scribe@tcp(mariadb:3306)/scribe?parseTime=true
    # Writes are disabled unless explicitly enabled and authenticated with a
    # Bearer token. Prefer injecting this from the environment.
    write_enabled: false
    # write_token: ${TRIPLET_PRESENTATION_WRITE_TOKEN}

# Identifier resolution. Exactly one source must be the default; additional
# sources are selected by identifier scheme (e.g. `https://…`).
sources:
  default: file
  file:
    # Filesystem root that identifiers resolve against. Identifiers are
    # treated as paths relative to this root; `..` is rejected.
    root: ./testdata/images
    # Optional local lookup for URL identifiers before HTTP streaming. When an
    # identifier starts with one of these decoded URL prefixes, Triplet strips
    # the prefix and checks the remaining path under the mapping root first.
    # url_mappings:
    #   - prefix: /sites/default/files
    #     root: /public
    #   - prefix: /system/files
    #     root: /private
    #     auth_probe: true
    #   - prefix: /fedora
    #     root: /fcrepo
    #     ocfl: true
    #     auth_probe: true
    # `ocfl: true` means the stripped path is a Fedora resource path stored
    # under an OCFL root, using extensions/0005-mutable-head/head/inventory.json.
    # `auth_probe: true` means Triplet forwards browser Cookie/Authorization
    # headers to the original URL and requires 200/206 before reading locally.
    # Auth probes are tiered: anonymous is checked first and cached separately;
    # credentialed probes only run when anonymous access is denied. Probe
    # decisions inherit sources.http.metadata_cache_ttl.
  # Optional HTTP(S) source. When configured alongside the file source,
  # `http://...` and `https://...` identifiers are routed here automatically.
  #
  # SECURITY: this allowlist is the main boundary for remote source images.
  # Triplet passes fetched source bytes to libvips, so keep this list to the
  # exact trusted upstream origins that may supply source images. Redirects are
  # checked against the same list. An empty list denies all HTTP sources and
  # wildcards are rejected.
  # Private, loopback, link-local, and metadata addresses are blocked unless
  # allow_private_hosts is explicitly enabled. Source caching does not bypass
  # these checks.
  # http:
  #   allowed_origins: [https://islandora-stage.lib.lehigh.edu]
  #   allow_private_hosts: false
  #   request_timeout: 2m
  #   max_bytes: 50MiB
  #   # Optional in-process metadata cache for remote URL identifiers. This lets
  #   # derivative cache hits reuse recent ETag/Last-Modified/size metadata
  #   # instead of making a HEAD or range request to the upstream source every
  #   # time. During this TTL, Triplet may serve a cached derivative without
  #   # noticing that the remote source changed or disappeared.
  #   metadata_cache_ttl: 5m

cache:
  # Derivative cache. Configure a filesystem root.
  root: /var/lib/triplet/cache
  # Best-effort aggregate size target for all cached derivative payload files
  # under cache.root. This controls retained cache footprint over time, not the
  # size of any single generated response. A write may temporarily exceed this
  # target before eviction runs, and metadata sidecar files are not counted.
  # 0 disables size-based eviction.
  max_bytes: 500GiB
  # Optional age limit for derivative entries. Expired entries are removed on
  # read and opportunistically during writes. 0 disables age-based eviction.
  max_age: 720h
  # Optional filesystem source cache for fetched source bytes (primarily HTTP
  # identifiers).
  # source_root: /var/lib/triplet/source-cache
  # Best-effort eviction target for the source cache. 0 disables size-based
  # eviction.
  source_max_bytes: 1GiB
  # When non-zero, stale source-cache hits are served immediately while a
  # background refresh fetches a fresh copy for later requests.
  source_stale_after: 24h

extensions:
  # Non-spec endpoint: POST multipart {image, region, size, rotation, quality, format}
  # → encoded derivative. Same pipeline as the spec routes.
  transform:
    enabled: true
    max_upload_bytes: 50MiB
  # Non-spec endpoint: POST bytes → mints an opaque identifier resolvable
  # via the standard /iiif/3/{id}/... routes.
  uploads:
    enabled: false