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 ¶
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 ¶
Cache is optional. Implementations must be safe for concurrent use. Only Resources produced by this package can contain non-empty immutable data.
type LimitError ¶
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.
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) 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 (*Resolver) Resolve ¶
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 ¶
BytesContext returns an owned copy while observing cancellation between bounded chunks. A canceled copy never exposes partially initialized bytes.
func (*Resource) DecodedBytes ¶
func (*Resource) EncodedBytes ¶
func (*Resource) PixelHeight ¶
func (*Resource) PixelWidth ¶
type SourceError ¶
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