standalone

package
v1.156.0 Latest Latest
Warning

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

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

Documentation

Overview

Package standalone turns an HTML or JSX asset into one HTML file that opens from disk with the network off (#2530).

A stored HTML asset names the platform's served runtimes by root-relative path (reveal.js under /portal/vendor/), its declared images and fonts by the reference route (/portal/refs/), and sometimes files on other hosts (a Google Fonts stylesheet, a CDN script). A JSX asset is a component the viewer compiles and runs against React, Recharts and lucide-react from an import map. Downloading the stored bytes hands the reader a file that renders none of that from file://. Build reads every one of those files, inlines it (a script as an inline script, a stylesheet as a style element, an image or a font as a data: URI) and, for JSX, compiles the component and bundles it with the libraries the platform serves under /portal/vendor/jsx/.

Some assets read the platform's data while they render: a declared CSV or JSON fetched at run time, an embedded form, a map reading the basemap archive. A file written from them would open without that data, so Build refuses them with a *PlatformDataError naming what they read, and the caller offers the stored source instead.

Build fetches nothing itself. It is handed two Fetchers: Own answers the platform's own paths in-process (the caller restricts it to the reference and vendor routes, which answer without a session), and External answers a URL on another host through the egress guard. Every fetch is bounded by Limits, and a file that cannot be fetched or is past a bound is left as its URL and reported as a Notice.

Index

Constants

View Source
const (
	TypeHTML = "text/html"
	TypeJSX  = "text/jsx"
)

The media types Build accepts.

Variables

View Source
var DefaultLimits = Limits{
	PerFile:     16 << 20,
	Total:       64 << 20,
	Files:       200,
	Timeout:     60 * time.Second,
	FileTimeout: 15 * time.Second,
}

DefaultLimits are the bounds an export runs under when the caller sets none.

View Source
var ErrTooLarge = errors.New("larger than the bound")

ErrTooLarge is a Fetcher's answer for a body past the limit it was given.

View Source
var ErrUnsupported = errors.New("only an HTML or JSX asset is exported as a standalone file")

ErrUnsupported is a document Build does not export.

Functions

This section is empty.

Types

type BuildError

type BuildError struct {
	Messages []string
}

BuildError is a JSX asset that does not compile, or imports a module the viewer does not provide.

func (*BuildError) Error

func (e *BuildError) Error() string

type Fetcher

type Fetcher interface {
	// Fetch returns the body and media type of u, reading at most limit
	// bytes; a body past limit is ErrTooLarge.
	Fetch(ctx context.Context, u *url.URL, limit int64) (body []byte, contentType string, err error)
}

Fetcher reads one URL.

type Input

type Input struct {
	// Document is the asset as its content route serves it: declared
	// references already rewritten to the reference route.
	Document []byte
	// ContentType is TypeHTML or TypeJSX.
	ContentType string
	// Title names the file's document, for a JSX asset that has no head.
	Title string
	// Origin is the deployment's origin as the reader reaches it; a URL at
	// it, or a root-relative path, is the platform's own.
	Origin *url.URL
	// Own reads a platform path; External a URL on another host.
	Own      Fetcher
	External Fetcher
	// Limits bounds the export; a zero field takes DefaultLimits'.
	Limits Limits
}

Input is one export.

type Limits

type Limits struct {
	// PerFile bounds one fetched file.
	PerFile int64
	// Total bounds every fetched file together.
	Total int64
	// Files bounds how many files are fetched.
	Files int
	// Timeout bounds the whole export; FileTimeout one fetch.
	Timeout     time.Duration
	FileTimeout time.Duration
}

Limits bound one export.

type Notice

type Notice struct {
	URL    string `json:"url"`
	Reason string `json:"reason"`
}

Notice is a file the export left as its URL, and why: the part of the document that still needs the network.

func Build

func Build(ctx context.Context, in Input) (doc []byte, notices []Notice, err error)

Build writes the standalone file for in, and names what it could not carry.

type PlatformDataError

type PlatformDataError struct {
	Reasons []string
}

PlatformDataError refuses an asset that reads the platform's data while it renders. Reasons are sentences a reader is shown.

func (*PlatformDataError) Error

func (e *PlatformDataError) Error() string

Jump to

Keyboard shortcuts

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