imageasset

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2026 License: MPL-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package imageasset resolves bounded local, HTTP, and data-URI image resources without depending on a renderer or scene representation. Animated GIF, APNG, and WebP resources use their first frame on the logical canvas; later frames are neither decoded nor charged to the decoded-pixel budget.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnavailable = errors.New("imageasset: source unavailable")

ErrUnavailable identifies a source whose bytes could not be fetched. It is reserved for absence and transport failures; malformed image data, policy limits, unsupported sources, and caller cancellation do not match it.

Functions

This section is empty.

Types

type Cache

type Cache interface {
	Get(key string) (*Resource, bool)
	Put(key string, resource *Resource)
}

Cache is optional. Implementations must be safe for concurrent use. Only Resources produced by this package can contain non-empty immutable data.

type Kind

type Kind uint8

Kind identifies how a resolved resource must be consumed.

const (
	KindRaster Kind = iota + 1
	KindSVG
)

func (Kind) String

func (k Kind) String() string

type LimitError

type LimitError struct {
	Name   string
	Actual int64
	Limit  int64
}

LimitError reports the exact inclusive ceiling that was exceeded.

func (*LimitError) Error

func (e *LimitError) Error() string

type Limits

type Limits struct {
	// MaxFetchedBytes bounds bytes read from a local file or HTTP response and
	// the encoded payload text of a data URI.
	MaxFetchedBytes int64
	// MaxEncodedBytes bounds the final PNG, JPEG, GIF, WebP, or SVG byte stream.
	MaxEncodedBytes int64
	// MaxDecompressedBytes bounds bytes after HTTP content decoding. Identity,
	// local-file, and data-URI sources are checked against it as well.
	MaxDecompressedBytes int64
	// MaxSVGBytes bounds raw or declared-compressed SVG XML before tokenization.
	// Callers that import resolved SVG must align this with the importer's
	// per-source byte ceiling.
	MaxSVGBytes int64

	MaxDecodedWidth  int
	MaxDecodedHeight int
	MaxDecodedPixels int64

	// MaxAssets bounds distinct successfully resolved canonical sources.
	MaxAssets int
	// MaxCumulativeEncodedBytes bounds immutable encoded bytes retained by one
	// Resolver session.
	MaxCumulativeEncodedBytes int64
	// MaxCumulativeDecodedBytes bounds unique canonical sources successfully
	// returned by one Resolver session. Raster resources, including animated
	// inputs represented by their first frame, charge at least width*height*4,
	// or eight bytes per pixel for 16-bit models; SVG resources charge their
	// strict raw byte length.
	MaxCumulativeDecodedBytes int64
}

Limits are caller-selected, inclusive ceilings. There are intentionally no package defaults: callers must choose budgets appropriate to their corpus.

func (Limits) Validate

func (l Limits) Validate() error

type MemoryCache

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

MemoryCache is a bounded, concurrency-safe LRU cache. It is never installed globally; callers explicitly own it, and Resolver namespaces every key.

func NewMemoryCache

func NewMemoryCache(maxEntries int, maxBytes int64) (*MemoryCache, error)

NewMemoryCache returns a cache with inclusive entry and encoded-byte limits.

func (*MemoryCache) Get

func (c *MemoryCache) Get(key string) (*Resource, bool)

func (*MemoryCache) Put

func (c *MemoryCache) Put(key string, resource *Resource)

type Options

type Options struct {
	// BaseDir resolves relative local paths. New makes it absolute; an empty
	// value freezes the current working directory at construction time.
	BaseDir    string
	HTTPClient *http.Client
	Cache      Cache
	// CacheNamespace is required when Cache is set. Reusing a namespace asserts
	// identical tenant, credentials, CookieJar, redirect policy, transport, and
	// fetch semantics for every Resolver sharing that cache.
	CacheNamespace string
	Limits         Limits
}

Options configures one independent resolver.

type Resolver

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

Resolver is one cumulative-budget session (normally one output document). It owns no global state and is safe for concurrent use.

func New

func New(options Options) (*Resolver, error)

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, source string) (*Resource, error)

Resolve resolves one image source and charges its decoded footprint before returning. Supported inputs are relative/absolute local paths, http(s) URLs, and data URIs. Animated GIF, APNG, and WebP resources retain their original bytes; native raster consumers deterministically paint the first animation frame on the format's logical canvas.

type Resource

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

Resource is immutable after construction. BytesContext returns an owned copy, so a cached Resource can safely be shared between goroutines and converted into a scene asset without exposing the cache's backing storage.

func (*Resource) BytesContext

func (r *Resource) BytesContext(ctx context.Context) ([]byte, error)

BytesContext returns an owned copy while observing cancellation between bounded chunks. A canceled copy never exposes partially initialized bytes.

func (*Resource) DecodedBytes

func (r *Resource) DecodedBytes() int64

func (*Resource) EncodedBytes

func (r *Resource) EncodedBytes() int64

func (*Resource) Kind

func (r *Resource) Kind() Kind

func (*Resource) MIMEType

func (r *Resource) MIMEType() string

func (*Resource) PixelHeight

func (r *Resource) PixelHeight() int

func (*Resource) PixelWidth

func (r *Resource) PixelWidth() int

type SourceError

type SourceError struct {
	Source string
	Op     string
	Err    error
}

SourceError associates an error with the external source and resolution stage. Data URI payloads are never copied into Source or error text.

func (*SourceError) Error

func (e *SourceError) Error() string

func (*SourceError) Unwrap

func (e *SourceError) Unwrap() error

Jump to

Keyboard shortcuts

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