imageopt

Documentation

Overview

Package imageopt provides the Node-free GoBeyond runtime image optimizer.

This package is AWS-free by design: it owns the Loader interface, the disk source, the HTTP handler, and the resize/re-encode path. The S3-backed source lives in the nested module github.com/Origens-Dev/gobeyond/imageopt/s3, so only deployments that read images from S3 pull the AWS SDK into their module graph.

Index

• Constants
• Variables
• func CacheSecondsFromEnvironment() int
• func DiskRootFromEnvironment(diskRoot string) (root string, ok bool)
• func Handler(loader Loader) http.Handler
• func NormalizeCacheSeconds(value int) (int, error)
• func NormalizeRemoteDomains(domains []string) ([]string, error)
• func S3SourceFromEnvironment() (configured bool, err error)
• func ValidatePrefix(prefix string) (string, error)
• func ValidateRemoteURL(source string, allowedDomains []string) (string, error)
• func ValidateSource(source string) (string, error)
• type DeploymentConfig
  • func LoadDeploymentConfig(root string) (DeploymentConfig, bool, error)
• type DiskLoader
  • func (loader DiskLoader) Open(_ context.Context, source string) (io.ReadCloser, error)
• type Loader
  • func NewLoaderFromEnvironment(_ context.Context, diskRoot string) (Loader, error)
• type RemoteLoader
  • func NewRemoteLoader(domains []string) (RemoteLoader, error)
  • func NewRemoteLoaderFromEnvironment() (*RemoteLoader, error)
  • func (loader RemoteLoader) Open(ctx context.Context, source string) (io.ReadCloser, error)
• type RouterLoader
  • func (loader RouterLoader) Open(ctx context.Context, source string) (io.ReadCloser, error)

Constants

const (
	DefaultCacheSeconds  = 3600
	MinCacheSeconds      = 60
	MaxCacheSeconds      = 31536000
	ImageCacheSecondsEnv = "GOBEYOND_IMAGE_CACHE_SECONDS"
)

const (
	// Route is the same-site runtime image optimization endpoint.
	Route = "/_gobeyond/image"

	// ImageSourceBucketEnv and ImageSourcePrefixEnv configure production S3
	// source loading. GOBEYOND_STATIC_DIR takes precedence for local development.
	ImageSourceBucketEnv = "GOBEYOND_IMAGE_SOURCE_BUCKET"
	ImageSourcePrefixEnv = "GOBEYOND_IMAGE_SOURCE_PREFIX"
	// ImageRemoteDomainsEnv is a comma-separated list of exact domains or
	// subdomain patterns (for example, images.example.com,*.ctfassets.net)
	// that the remote image loader may fetch.
	ImageRemoteDomainsEnv = "GOBEYOND_IMAGE_REMOTE_DOMAINS"
	// ImageErrorHeader identifies validation or source failures without
	// exposing the requested URL, which may contain sensitive query values.
	ImageErrorHeader = "X-GoBeyond-Image-Error"
)

const DeploymentConfigPath = ".gobeyond/images.json"

Variables

var (
	ErrInvalidSource = errors.New("invalid same-site image source")
	ErrNotFound      = errors.New("image source not found")
)

var DefaultWidths = []int{16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840}

DefaultWidths bounds the variants the runtime will generate.

Functions

func CacheSecondsFromEnvironment

func CacheSecondsFromEnvironment() int

func DiskRootFromEnvironment

func DiskRootFromEnvironment(diskRoot string) (root string, ok bool)

DiskRootFromEnvironment resolves the disk image source: diskRoot when set, otherwise GOBEYOND_STATIC_DIR. ok is false when neither is configured.

func Handler

func Handler(loader Loader) http.Handler

Handler returns an HTTP handler for Route.

func NormalizeCacheSeconds

func NormalizeCacheSeconds(value int) (int, error)

func NormalizeRemoteDomains

func NormalizeRemoteDomains(domains []string) ([]string, error)

NormalizeRemoteDomains validates and canonicalizes domain allowlist entries.

func S3SourceFromEnvironment

func S3SourceFromEnvironment() (configured bool, err error)

S3SourceFromEnvironment reports whether a complete, valid S3 image source is configured. It errors when the bucket and prefix disagree about being set or when the prefix is unsafe, so the imageopt/s3 module and AWS-free builds report the same misconfiguration.

func ValidatePrefix

func ValidatePrefix(prefix string) (string, error)

ValidatePrefix normalizes a storage prefix, rejecting traversal and empty segments. It is exported for out-of-package Loader implementations.

func ValidateRemoteURL

func ValidateRemoteURL(source string, allowedDomains []string) (string, error)

ValidateRemoteURL canonicalizes a remote source and checks its domain allowlist. Remote source URLs may not carry query strings or fragments.

func ValidateSource

func ValidateSource(source string) (string, error)

ValidateSource normalizes a same-site image source into a safe relative path. Loader implementations outside this package (e.g. imageopt/s3) must call it before touching any storage.

Types

type DeploymentConfig

type DeploymentConfig struct {
	RemoteDomains []string `json:"remoteDomains"`
	CacheSeconds  int      `json:"cacheSeconds,omitempty"`
}

DeploymentConfig is the repo-owned image configuration. The deployment pipeline converts it to runtime environment configuration after validation.

func LoadDeploymentConfig

func LoadDeploymentConfig(root string) (DeploymentConfig, bool, error)

LoadDeploymentConfig reads the optional repo-owned image configuration. Missing configuration means that the deployment has no remote image sources; same-site disk/S3 sources remain available.

type DiskLoader

type DiskLoader struct {
	Root string
}

DiskLoader reads static files beneath Root.

func (DiskLoader) Open

func (loader DiskLoader) Open(_ context.Context, source string) (io.ReadCloser, error)

Open securely resolves source beneath the configured static root.

type Loader

type Loader interface {
	Open(context.Context, string) (io.ReadCloser, error)
}

Loader opens a same-site static path. Implementations must not interpret it as a remote URL.

func NewLoaderFromEnvironment

func NewLoaderFromEnvironment(_ context.Context, diskRoot string) (Loader, error)

NewLoaderFromEnvironment selects a disk source when diskRoot (or GOBEYOND_STATIC_DIR) is set, and reports no loader when nothing is configured. This package is deliberately AWS-free: S3-backed sources live in the nested github.com/Origens-Dev/gobeyond/imageopt/s3 module, whose s3.NewLoaderFromEnvironment adds the S3 branch to this same environment contract.

type RemoteLoader

type RemoteLoader struct {
	Client         *http.Client
	AllowedDomains []string
}

RemoteLoader fetches public HTTPS images from an explicit domain allowlist. It intentionally does not forward viewer headers or credentials.

func NewRemoteLoader

func NewRemoteLoader(domains []string) (RemoteLoader, error)

NewRemoteLoader creates a remote loader with the default SSRF-safe client.

func NewRemoteLoaderFromEnvironment

func NewRemoteLoaderFromEnvironment() (*RemoteLoader, error)

NewRemoteLoaderFromEnvironment reads ImageRemoteDomainsEnv. It returns nil when remote loading is not configured.

func (RemoteLoader) Open

func (loader RemoteLoader) Open(ctx context.Context, source string) (io.ReadCloser, error)

type RouterLoader

type RouterLoader struct {
	Local  Loader
	Remote Loader
}

RouterLoader selects a remote loader for absolute HTTPS URLs and a local loader for same-site paths. It lets a deployment optimize both its own static assets and explicitly allowlisted public remote assets.

func (RouterLoader) Open

func (loader RouterLoader) Open(ctx context.Context, source string) (io.ReadCloser, error)