assets.h File Reference

Content-hashed, in-memory static assets served by a cwist_app. More...

#include <cwist/sys/err/cwist_err.h>
#include <stddef.h>

Include dependency graph for assets.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CWIST_ASSET_DEFAULT_PREFIX   "/assets"
#define	CWIST_ASSET_IMMUTABLE_CACHE   "public, max-age=31536000, immutable"

Functions
cwist_error_t	cwist_app_asset_prefix (struct cwist_app *app, const char *url_prefix)
	Choose the URL prefix assets are served under.
cwist_error_t	cwist_app_asset_add (struct cwist_app *app, const char *name, const void *data, size_t len, const char *content_type)
	Register an asset from memory. The data is copied.
cwist_error_t	cwist_app_asset_add_file (struct cwist_app *app, const char *name, const char *path, const char *content_type)
	Register an asset from a file, read once now.
const char *	cwist_app_asset_url (struct cwist_app *app, const char *name)
	Content-hashed URL of the newest asset registered under name.

Detailed Description

Content-hashed, in-memory static assets served by a cwist_app.

An asset is registered under a logical name ("css/app.css") and served at a URL that embeds a hash of its content ("/assets/css/app.3f2a9c1d0b7e6a54.css"), with a one-year immutable cache lifetime. Changing the content changes the URL, so browsers and proxies never serve a stale copy, and unchanged content keeps its URL across restarts and across prefork workers.

Typical use: bundle and minify the stylesheets produced by the CSS composer and component scopes (cwist_css_bundle()), register the result, and emit cwist_app_asset_url() in the page layout.

Assets are served on a route miss, before static directories, through the app's middleware chain, and also work in the WASM builds (no filesystem is needed unless cwist_app_asset_add_file() is used).

Definition in file assets.h.

Macro Definition Documentation

CWIST_ASSET_DEFAULT_PREFIX

#define CWIST_ASSET_DEFAULT_PREFIX   "/assets"

Default URL prefix for assets.

Definition at line 33 of file assets.h.

CWIST_ASSET_IMMUTABLE_CACHE

#define CWIST_ASSET_IMMUTABLE_CACHE   "public, max-age=31536000, immutable"

Cache-Control sent with content-hashed asset URLs.

Definition at line 36 of file assets.h.

Function Documentation

cwist_app_asset_add()

cwist_error_t cwist_app_asset_add	(	cwist_app *	app,
		const char *	name,
		const void *	data,
		size_t	len,
		const char *	content_type
	)

Register an asset from memory. The data is copied.

The asset is served at <prefix>/<hashed name>, where the hashed name puts the first 16 hex digits of the SHA-256 of data before the last extension ("css/app.css" -> "css/app.<hash>.css"), with ETag, Cache-Control: CWIST_ASSET_IMMUTABLE_CACHE and 304 answers to a matching If-None-Match. The logical name is also served, at <prefix>/<name>, with Cache-Control: no-cache, for tools that cannot know the hash.

Adding a name again with different content publishes a new hashed URL; the previous one keeps working until the app is destroyed, so pages cached with the old URL still load. Adding identical content again changes nothing. Register assets before cwist_app_listen(): prefork workers only see what existed when they were forked.

Parameters

app	App that serves the asset.
name	Logical name: ASCII letters, digits, '.', '-', '_', '~' and '/' separated segments, no leading or trailing '/', no empty, "." or ".." segment.
data	Content (may be NULL only when len is 0).
len	Content length in bytes.
content_type	Content-Type to send; NULL picks one from the extension.

Returns

0 on success, -1 on invalid arguments or allocation failure (err_i16 channel).

Register an asset from memory. The data is copied.

Copies data; on success the asset is immutable and served under its content-hashed name. Duplicate content is a no-op.

Parameters

app	App instance; must not be NULL.
name	Logical asset name; must be a valid relative path.
data	Asset bytes; may be NULL only when len is 0.
len	Length of data in bytes.
content_type	Optional Content-Type override; if NULL a type is guessed from name.

Returns

Error result with code 0 on success, -1 on invalid arguments or allocation failure.

Definition at line 306 of file assets.c.

References cap, and cwist_alloc().

cwist_app_asset_add_file()

cwist_error_t cwist_app_asset_add_file	(	cwist_app *	app,
		const char *	name,
		const char *	path,
		const char *	content_type
	)

Register an asset from a file, read once now.

Parameters

app	App that serves the asset.
name	Logical name, same rules as cwist_app_asset_add().
path	File to read.
content_type	Content-Type to send; NULL picks one from name.

Returns

0 on success, -1 on invalid arguments, a read error or allocation failure (err_i16 channel).

Register an asset from a file, read once now.

The file is read fully into memory; on success its content is served like an asset added with cwist_app_asset_add().

Parameters

app	App instance; must not be NULL.
name	Logical asset name; must be a valid relative path.
path	Filesystem path to read; must not be NULL.
content_type	Optional Content-Type override; if NULL a type is guessed from name.

Returns

Error result with code 0 on success, -1 on invalid arguments, an unreadable file, or allocation failure.

Definition at line 336 of file assets.c.

References cap, cwist_alloc(), cwist_free(), and cwist_realloc().

cwist_app_asset_prefix()

cwist_error_t cwist_app_asset_prefix	(	cwist_app *	app,
		const char *	url_prefix
	)

Choose the URL prefix assets are served under.

Must be called before the first asset is added, since URLs already handed out would otherwise stop resolving.

Parameters

app	App to configure.
url_prefix	Absolute path such as "/static/build"; "/" serves assets at the root. Trailing slashes are ignored.

Returns

0 on success; -1 on invalid arguments, when assets were already added, or on allocation failure (err_i16 channel).

Choose the URL prefix assets are served under.

Must be called before any asset is registered; fails once the registry is non-empty.

Parameters

app	App instance; must not be NULL.
url_prefix	Absolute path such as "/assets" (trailing '/' stripped), or "/" for the root.

Returns

Error result with code 0 on success, -1 on failure (NULL app, invalid prefix, or assets already registered).

Definition at line 197 of file assets.c.

References cap, and cwist_free().

cwist_app_asset_url()

const char * cwist_app_asset_url	(	cwist_app *	app,
		const char *	name
	)

Content-hashed URL of the newest asset registered under name.

Returns

App-owned string valid until the app is destroyed, or NULL when no asset has that name.

Content-hashed URL of the newest asset registered under name.

The returned string is owned by the asset registry and stays valid until the app is destroyed.

Parameters

app	App instance; must not be NULL.
name	Logical asset name.

Returns

Asset URL, or NULL if no such asset exists.

Definition at line 386 of file assets.c.

References cap.