- Status: 0.1 baseline
- Date: 2026-08-28
- Standing: the only contract a plugin has. Official and third-party plugins use the same mechanism; there is no private interface. The boundaries described here must match the wording in the admin interface — nothing may imply a sandbox exists.
A plugin is real JavaScript or TypeScript that reaches five hooks and seven
capabilities through a declarative plugin.json. It runs in the user's own
Cloudflare account with the Worker's full permissions. Plugin API 2 adds
optional hooks and capabilities on top of these (§13).
Official and third-party plugins take the same path: source into
src/plugins/, bundled into the Worker at build time. The only difference is
who wrote it and who is responsible for it.
| Action | How it takes effect | Who does it |
|---|---|---|
| Install, update or remove a plugin | Edit source, redeploy | Someone technical |
| Enable or disable an installed plugin | A switch in the admin, immediate | The operator |
| Change settings and secrets | A form in the admin, immediate | The operator |
The switch decides only whether the code runs; it does not change what code is in the artifact. That is why it can be immediate, and it is what separates it from installing.
"Immediate" is about the setting, and reaches visitors through the cache
like any other change. Switching a plugin on or off, and saving its
settings, ask Cloudflare to purge every cached page (the site tag) — when
the site has a purge token (CLOUDFLARE_RESOURCES.md §6). Through
0.1.0-rc.11 a purge that fails is neither shown nor logged, and on the
project's own deployed test site these purges were observed not to take
effect (tasks/TASK-46.md §7); do not rely on it without checking. Without one, which includes every
local wrangler dev, nothing is purged: a page cached while the plugin was
off keeps its [[inquiry]] marker, and one cached while it was on keeps a
form whose route is gone, until the page's cache lifetime runs out. That is
the same honest degradation as for content and settings, not a separate
defect; the wizard shortens the lifetime to 60 seconds on a site without a
token for this reason. Locally, Wrangler keeps the cache on disk under
.wrangler/state/v3/cache; deleting that folder with the server stopped
empties it.
The interface must not make installing a plugin look like a single click — it cannot be, and pretending otherwise is exposed the first time a user tries. The correct interface tells the user that source must change and a build must run, and gives them the steps.
A plugin is trusted code (ARCHITECTURE §14). It can read and write the
entire database, call any external service, and read every secret. There is
no sandbox, and there will not be one. The risk boundary is the same as a
WordPress plugin's: the user is responsible for what they install.
The documentation and the interface must say this outright. Concealing it is more dangerous than the absence of a sandbox.
A plugin is built by calling definePlugin once, at module scope, and
exporting the result:
import { definePlugin } from 'mallok/worker';
import manifest from './plugin.json';
export default definePlugin({ manifest, hooks: { … }, routes: { … } });It exists because the runtime reads manifest.hooks and manifest.settings
directly. Mallok's own plugins are fine — their manifests come from
plugin.json through a schema that supplies every default — but both fields
are optional in the format below, so a hand-written manifest made the
runtime throw Cannot read properties of undefined on a visitor request,
from inside Mallok, naming nothing the author could act on. definePlugin
runs the same schema, so a hand-written object and a parsed file end up
identical.
It then checks the two halves against each other, and refuses:
| What | Why it is worth failing a build over |
|---|---|
| A hook the manifest declares with no implementation | The runtime calls what the manifest lists, so it does nothing — silently, on every request |
| An implemented hook the manifest does not declare | It never runs, and its author has no way to tell |
| The same, for routes | A declared route with no handler answers 500; an undeclared one is never mounted |
| A hook name that is not one of the five | Named in the message, because zod's own error lists the allowed options and not the offending value |
| Anything the manifest schema rejects | An id that cannot form a table prefix, a settings field of an unknown type, a panel table without the plugin's p_<id>_ prefix |
Every refusal names the plugin. definePlugin runs when the Worker module is
initialised; a bad plugin therefore prevents that Worker from initialising,
rather than turning into a later plugin-route failure. A bundler that only
transforms modules does not execute it, so Mallok's package gate also imports
and executes the built artifact.
Refusals are PluginDefinitionError, which carries a hint alongside its
message.
src/plugins/inquiry/
├── plugin.json # declares hooks, routes, settings, secrets, panels, injected client JS
├── migrations/
│ └── 0001_inquiry.sql # table names must start with p_inquiry_
├── emails/ # optional: email templates (Liquid, through the same restricted engine)
│ ├── notify.en.liquid
│ └── autoreply.en.liquid
└── index.ts # the implementation; exports only what plugin.json declares
Unknown fields are rejected at every manifest level; they are never silently
discarded. Migrations and executable handlers live beside the manifest in the
object passed to definePlugin, because JSON cannot contain code.
official is deliberately not a manifest field. Mallok marks the plugin it
ships through an internal registry that is not exported from mallok/worker.
A third-party manifest containing "official": true is rejected instead of
receiving an origin badge it can award itself.
The field types in settings match the table in THEME_FORMAT.md §5.2,
excluding image, file and reference. Validation uses zod, with the
schema generated from plugin.json. A setting may carry "advanced": true
(any API version): the admin draws it after the others in a closed "More
options" block, with the plugin's optional secrets. A required setting may
not be marked, and the manifest is refused if one is (ADMIN_SIMPLE.md,
D9).
0.1 exposes five (ARCHITECTURE §12); plugin API 2 adds renderData and
onContentDelete.
Implementations are properties of the hooks object passed to definePlugin.
| Hook | When | Whose CPU it costs | Typical use |
|---|---|---|---|
onRequest |
A request arrives, before the cache lookup | The visitor request | Redirects, access control |
beforeRender |
Stage one, once the mdast exists | The save request | Shortcodes, custom syntax |
afterRender |
After the complete HTML is generated | The visitor request, on a cache miss | Injecting meta, structured data, form markup |
onContentSave |
When content is saved | The save request | Validation, auto-summaries, notifying something external |
scheduled |
Inside the once-a-minute cron | The cron invocation | Retries, syncing, cleanup |
onContentDelete (API 2) |
After content has been deleted | The delete request | Removing what the plugin kept for that content |
renderData (API 2) |
While a page is rendered, on a cache miss only | The visitor request, on a cache miss | Data from the plugin's tables that templates print: prices, availability |
export async function onRequest(
request: Request,
ctx: PluginRequestContext,
): Promise<Response | undefined>;Returning a Response short-circuits the request; returning undefined
continues. It runs before the cache lookup, so every visitor request pays
its CPU cost — including the ones the cache would otherwise have answered
directly. Writing something heavy here destroys the design goal that a cache
hit costs almost nothing (ARCHITECTURE §2). The admin must say so when a
plugin declaring onRequest is enabled.
import type { Root as MdastRoot } from 'mdast';
export function beforeRender(
tree: MdastRoot,
ctx: { readonly frontmatter: Readonly<Record<string, unknown>> },
): void | Promise<void>;The signature is BeforeRenderHook in src/core/fragment.ts. It operates on
mdast, remark's AST — the only reason unified was chosen over marked or
markdown-it (TECH_STACK §4).
It must be pure: no input beyond the AST, the front matter and the
plugin's settings. It may not read the clock, a random source, anything about
the request, or the database. The reason is the determinism rule in
ARCHITECTURE §5 — identical input must produce byte-identical HTML, or
neither the fragment cache nor the regression tests hold.
Contract-version warning:
beforeRender's parameter type is bound to remark's mdast. Should the core ever change Markdown engine (the open decision inTASK-01 §6), this signature necessarily breaks, andpluginApimust go to a new version rather than degrade silently — 3, since 2 is the additive version in §13. 0.1 defines the contract against unified and mdast.
export async function afterRender(
html: string,
ctx: PluginRenderContext,
): Promise<string>;Receives the complete page HTML and returns modified HTML. The plugin is responsible for escaping what it injects — the core's sanitisation happened in stage one and is already past. A plugin is trusted code, so this is its job, but the documentation has to say so plainly.
interface PluginRenderContext {
readonly settings: Readonly<Record<string, unknown>>;
readonly site: SiteSettings;
readonly locale: string;
/** The active theme's language pack for this page: what templates read as `t`. */
readonly t: Readonly<Record<string, string>>;
readonly path: string;
/** Kind and id of the content being rendered; null on home and list pages. */
readonly content: { readonly id: string; readonly kind: string } | null;
}ctx.t is how injected markup speaks the page's language. It is the
theme's language pack as its templates see it (THEME_FORMAT.md §10): the
page's locale laid over the theme's default one. A plugin picks its own
keys, prefixed with its id, reads them from ctx.t, and falls back to text
of its own for a key the theme does not define — a theme is not obliged to
know about any plugin. The values are the theme's text, not markup: escape
them like anything else. Available to every plugin, whichever API version it
declares.
The official inquiry plugin reads inquiry_name, inquiry_email,
inquiry_company, inquiry_phone, inquiry_message and inquiry_submit
this way. Its own text covers English and Chinese; a theme that defines
those six keys in its packs gives the form every language the theme has. A
key that is absent or blank falls back, one key at a time.
export async function onContentSave(
content: ContentDraft,
ctx: PluginContext,
): Promise<{ readonly markdown?: string } | void>;Returning a replacement markdown adopts that value; all other draft fields
remain owned by Mallok. Returning void changes nothing.
Throwing fails the save and returns the error to the caller — that is the
legitimate way for a plugin to refuse a save, and it is better than
rewriting silently.
It is called on every save: the admin's editor, mallok publish and
mallok import, a starter's content at setup — they all go through
POST /_mallok/api/content, and that is where the hook runs. (Until
0.1.0-rc.9 this hook was documented and never called.) The draft is what
was submitted:
interface ContentDraft {
readonly kind: string;
readonly locale: string;
readonly slug: string;
readonly title: string;
readonly markdown: string; // front matter included
readonly frontmatter: Readonly<Record<string, unknown>>;
readonly status: string; // draft | scheduled | published, as requested
}The order on the save path, which decides what a hook can rely on:
- The submitted Markdown is parsed; its kind, locale, slug and title are settled. A hook cannot change those: the slug and locale are the item's identity, and they are taken from what was submitted even when a hook rewrites the front matter.
- The hooks run, in the order the site lists its plugins, each receiving the Markdown the one before it returned.
- The result is parsed again. It must still be a document that can be saved — front matter with a title, within the size limit — or the save fails with 422 and nothing is stored.
- The length safety net applies to the result: a hook that makes a body
too long to render safely gets the item saved as a draft, like any other
over-long item (
ARCHITECTURE §5). - The result is compared with what is stored. If nothing would change,
the save answers
unchangedand writes nothing. - Stage one renders the result, and the result is what is stored.
Three things follow:
- A hook must be idempotent: given its own output, it returns it
unchanged; given the same input, it returns the same output. Step 5 is what
keeps a second
mallok publishof the same file a no-op, and it only works if the hook gives the same answer twice. A hook that stamps a timestamp makes every publish a change. - What is stored is what the hook returned, so an export contains it and the file in the author's repository does not. A hook that rewrites Markdown is changing the author's source of truth; prefer refusing.
- A refusal is answered 422 with
{ "error": <the message thrown>, "rejectedBy": <plugin id> }, shown as it is by the admin and bymallok publish. Nothing is written and later hooks do not run. Write the message for the person saving.
The hook's time is the save request's time. A save already runs stage one, which is the most expensive thing Mallok does; a hook that makes a network call or a slow query can push a save past the platform's CPU limit, where it is killed without an error the caller can read. Validate, look something up in your own table, and return.
A draft has no id: a new item does not have one until it is stored. To keep
a plugin's own rows in step with content, key them by kind, locale and
slug, or attach them later (§7.5, Task 29).
export async function scheduled(ctx: PluginContext): Promise<void>;Runs inside the site's single cron (* * * * *). Every plugin's scheduled
shares one invocation's 10 ms CPU budget on the free plan. A plugin must
therefore batch its own work: do a little, leave the rest for the next minute,
and do not try to finish everything at once.
Each plugin's hook runs inside its own try/catch. One that throws is
logged as plugin_scheduled_error with the plugin's id and the others still
run. That contains an exception, not a budget: a hook that uses up the
invocation's CPU takes the rest of the tick with it, which no catch can
prevent.
For work that must happen and may fail, queue a job (§7.4) instead of doing it here.
export async function renderData(
ctx: PluginRenderDataContext,
): Promise<Readonly<Record<string, unknown>> | undefined>;Plugin API 2; the manifest must declare "pluginApi": 2 and list
renderData in hooks. It is the only hook on the render path that may read
the database, and it exists so that what a plugin stores — a price, an
availability state — is in the cached HTML, not fetched by the browser.
When it runs. Once per rendered page: a content page, a kind's list, a tag
archive, the home page. Never on a cache hit, never for a 404, and never in
mallok build or the admin's preview, which run no plugin code — there
plugins is empty. The hooks of all plugins run concurrently, alongside the
core's own second round trip.
What it returns. An object, or undefined for "nothing on this page".
The core passes it through JSON.stringify, so it must be JSON-serialisable:
a function is dropped, and a cycle or a BigInt fails the hook. Templates
read it as plugins.<plugin_id> — the plugin's id with hyphens written as
underscores, as in its table prefix (THEME_FORMAT.md §7.9). The core does
not rename keys; use snake_case, as the rest of the view does. Return
values ready to display — a price already formatted for ctx.locale — since
a plugin cannot register Liquid filters (§12). Strings are HTML-escaped by the
template engine like any other value.
Structured data. One key of the result is not for templates:
structuredData. It holds properties for the JSON-LD node the core already
emits for the page, so that a price a plugin puts on the page is in the
page's structured data too:
return {
price: '$99.00',
structuredData: {
offers: { '@type': 'Offer', price: '99.00', priceCurrency: 'USD',
availability: 'https://schema.org/InStock' },
},
};The core merges them into its own node and emits one node, through the
same serialisation and the same escaping as before (SEO_PERFORMANCE.md §5).
This is the only way in: a theme template may not contain an inline
<script>, a JSON-LD data block included, whether or not it declares
clientScripts (THEME_FORMAT.md §9). The rules:
- An allow-list per node type decides what may be added. Today it has one
entry:
offerson aProductnode, which is what a content page of theproductkind gets. Nothing may be added to anArticle,FAQPageor the home page's node, and a page with no node — a plain page, a list, a tag archive — gets none from a plugin. - The core's own properties are never replaced:
@context,@type,name,urland whatever else the core set on that node. - When two plugins offer the same property, the first in the site's plugin order keeps it.
- Every property that is not used is logged:
{"event":"structured_data_dropped","plugin":…,"key":…,"reason":…,"path":…}with the reasonnot_allowed,core_key,already_set,no_node, ornot_objectwhenstructuredDataitself is not an object. Dropping is not a failure: the page is exactly what the core alone would have produced, and it is cached. structuredDatais removed before the result reaches templates; there is noplugins.<id>.structuredData.- Offer only what the page shows — the same price, in the same currency,
and an availability the page prints. Search engines penalise structured
data that says more than the page (
SEO_PERFORMANCE.md §5), and the allow-list cannot check that for you.
What it costs, and the limits that follow. A cold render may make four D1
round trips (ARCHITECTURE §4) and the core uses two. So:
- One database call per hook per render: one query, or one
batch. Thectx.dbthe hook receives counts calls and refuses a second. On a list or home pagectx.itemsholds every item shown, so oneIN (…)query covers the page. - At most two plugins run
renderDataon a page. They are the first two enabled plugins that implement it, in the order the site lists its plugins increateMallok. A further one is skipped, and{"event":"render_data_skipped"}is logged with its id; the page is otherwise normal and is cached.
Read-only. ctx.db accepts a single statement that starts with SELECT,
or with WITH and contains no INSERT, UPDATE or DELETE. Anything else
is refused before it reaches D1, as are exec, dump, withSession and a
statement prepared on another binding. The check is by keyword, not by
parsing SQL: it catches a mistake, it is not a sandbox (§2.1), and it can
refuse a legitimate query that spells one of those words or a ; inside a
string literal — bind the value as a parameter instead.
Deterministic. The result may depend only on the database and on the context below: not on the clock, a random source or anything about the request, none of which the hook is given. The page is stored in the edge cache and served to everyone, and identical database state must give identical bytes.
When it fails. A hook that throws, makes a second call, attempts a write
or returns something that is not an object loses its own data and nothing
else: the page renders, the other plugins' data is present,
{"event":"render_data_failed","plugin":…,"path":…,"reason":…} is logged, and
that response is not stored in the edge cache (cache-control: no-store),
so the next request tries again. A hook that catches the refusal of its
second call and carries on is treated as failed all the same. A template must
therefore read plugins.<id> as optional.
Freshness. What the hook read is cached with the page. A later change in the plugin's tables reaches visitors when that page's cache entry is purged or expires. So the hook says what the page depends on, in a second reserved key:
return {
price: '$99.00',
cacheTags: [`product-${ctx.content.id}`],
};Each tag is added to the page's Cache-Tag as p:<plugin-id>:<tag>, and the
route or action that changes the data calls
ctx.purgeTags(['product-…']) with the same short name (§9). Like
structuredData, cacheTags is removed before the result reaches templates.
export async function onContentDelete(
ref: ContentDeleteRef,
ctx: PluginContext,
): Promise<void>;
interface ContentDeleteRef {
readonly id: string;
readonly kind: string;
readonly locale: string;
readonly translationGroup: string;
readonly lastInGroup: boolean;
}Plugin API 2. Called after content has been deleted through
DELETE /_mallok/api/content/<id>, so that a plugin can remove what it kept
for it — a product's variants and prices, say.
lastInGroupis true when no other language of the item is left. One language of a product being deleted usually means "that translation is gone"; the last one means "the product is gone". Rows a plugin keys bytranslationGroupbelong to the second case.- It cannot refuse the delete, and a failure does not undo it. The
content is already gone when the hook runs. A hook that throws is logged
as
{"event":"content_delete_hook_failed",…}, the other plugins' hooks still run, and the response carries"hookFailed": [<plugin ids>]so that whoever deleted the item knows a plugin's cleanup did not finish. Make the cleanup safe to repeat, and letscheduledsweep up what was missed. - It is not called when content is unpublished or made a draft — that is a
save, and
onContentSavesees the newstatus— nor when a plugin is switched off at the time; a plugin that is later switched on finds no record of deletions it missed. - Like a save hook, its time is the request's time. Delete rows; do not call out.
All of these are exported from mallok/worker, so a third-party plugin
annotates its own handlers with the same types the official one uses:
PluginContext, PluginRequestContext, PluginRenderContext,
PluginRenderDataContext, ContentDraft, ContentDeleteRef, RouteInput, PluginPageResult,
PluginRecordInput, PluginRecordHandlers, MoneyValue, EmailMessage, PluginSiteSettings,
PluginExportFile and PluginMigration, plus MallokPlugin and
PluginInput. There is no private interface (§1), and before 0.1.0-rc.5 the
package exported only MallokPlugin with an opaque
manifest — enough to name a plugin and not enough to write one.
interface PluginContext {
readonly db: D1Database;
readonly media: R2Bucket;
/** This plugin's values in plugin_state.settings, validated against the schema. */
readonly settings: Readonly<Record<string, unknown>>;
/** Decrypted secrets. Never logged, never returned to a client. */
readonly secrets: Readonly<Record<string, string>>;
readonly site: SiteSettings;
/** Provided by the core, see §7.6. */
readonly sendEmail: (message: EmailMessage) => Promise<string>;
/** Purge this plugin's own cache tags, or `site`; coalesced. See §9.1. */
readonly purgeTags: (tags: readonly string[]) => Promise<PurgeOutcome>;
/** Queues one of the plugin's own jobs; resolves to the job's id (§7.4). */
readonly enqueue: (
name: string,
payload: unknown,
options?: { readonly runAt?: Date },
) => Promise<string>;
/** The same job as a statement for the plugin's own `db.batch` (§7.4). */
readonly enqueueStatement: (
name: string,
payload: unknown,
options?: { readonly runAt?: Date },
) => D1PreparedStatement;
readonly waitUntil: (promise: Promise<unknown>) => void;
}Links to public pages. ctx.site.prefixDefaultLocale is true on a site
that prefixes its default locale as well (ARCHITECTURE.md §9). Do not test
locale === ctx.site.defaultLocale to decide on a prefix; build the path
with the exported helper, which is what the core and the inquiry plugin use:
import { localePrefix } from 'mallok/worker';
const thanks = `${localePrefix(ctx.locale, ctx.site)}/thank-you`; // '/thank-you', '/de/thank-you', or '/en/thank-you'interface PluginRenderDataContext {
/** One call per render, reads only (§5.6). Not the plain binding. */
readonly db: D1Database;
readonly settings: Readonly<Record<string, unknown>>;
readonly site: SiteSettings;
readonly locale: string;
readonly path: string;
/** Content pages: the item being rendered. Home and list pages: null. */
readonly content: {
readonly id: string;
readonly kind: string;
readonly translationGroup: string;
readonly frontmatter: Readonly<Record<string, unknown>>;
} | null;
/** Home and list pages: the items shown on this page. Empty on a content page. */
readonly items: readonly {
readonly id: string;
readonly kind: string;
readonly translationGroup: string;
}[];
}PluginRenderDataContext has no secrets, no media, no sendEmail and no
request: it runs on the visitor path and its output is public and cached.
PluginRequestContext adds request, url, locale, country and the
one-way ipHash. For a route, locale is the request's locale segment when
there is one and the site default otherwise (§7.2); for onRequest it is the
site default. PluginRenderContext contains settings, site, locale,
path and the optional { id, kind } content identity. It deliberately has
neither secrets nor database access.
ctx.db is the full D1 binding — a plugin can read and write any table.
The core enforces no table-level isolation, because that would offer a false
sense of security. The convention is: a plugin touches only its own
p_<id>_-prefixed tables, may read core tables, and needs a good reason to
write to one.
A plugin brings its own SQL migrations. Table names must start with
p_<plugin_id>_ and migration ids with plugin:<plugin_id>:
(DATA_MODEL §2.11). The core's migrator runs them alongside the core
migrations, records them in the same migration table, and shares the same
migration_lock.
The migrations array is executable plugin input, not manifest JSON.
definePlugin rejects malformed entries, ids outside that prefix and
duplicate ids before the composition is installed.
The migration rules are the core's (DATA_MODEL §2.10): additive changes
only — new tables, new columns with defaults, new indexes. Dropping a column
or changing its meaning within one version is not allowed, because the old
Worker version is still serving during the migration.
Disabling or removing a plugin from the build does not drop its tables. 0.1 has no automated plugin-data deletion flow; removal leaves that data in D1 unless an operator performs a separate, deliberate migration.
/_mallok/p/<plugin_id>/<path>, declared in plugin.json's routes. The
core handles:
- matching the path, its parameters and its locale segment (below);
- body parsing (
application/jsonandapplication/x-www-form-urlencoded); - the server-side Turnstile
siteverify, whenturnstile: true; - rate limiting, through the
RATE_LIMITERWorkers binding.
export const routes = {
async submit(input: SubmitInput, ctx: PluginRequestContext): Promise<Response> { … },
};Paths (plugin API 2). A path is one to six segments separated by /.
Each is a name (orders: lowercase letters, digits and hyphens, starting
with a letter) or a parameter (:orderNo: letters and digits); the first is
always a name.
"routes": [
{ "path": "cart", "method": "GET" },
{ "path": "orders/new", "method": "GET" },
{ "path": "orders/:orderNo", "method": "GET" }
]export const routes = {
'orders/:orderNo': async (input: RouteInput, ctx: PluginRequestContext) => {
const order = await findOrder(ctx.db, input.params.orderNo);
…
},
};- A handler is keyed by the path exactly as declared.
input.paramsholds what each parameter captured, percent-decoded. A segment that is not valid encoding, is empty, is longer than 200 characters, or decodes to.,..or something containing/matches no route: the answer is 404. A parameter is otherwise unvalidated text from the visitor — bind it, never splice it into SQL or HTML.- A name beats a parameter in the same position, so
orders/newis not taken for an order number; between routes equally specific, the first declared wins. Two routes that would match the same requests (orders/:orderNoandorders/:id) are refused at build time. - A doubled or trailing slash matches nothing.
The locale segment (plugin API 2). In
/_mallok/p/<plugin_id>/<locale>/<path>, a first segment that is one of the
site's enabled locales is the request's locale: it sets ctx.locale and is
not part of the path. /_mallok/p/shop/de/cart and /_mallok/p/shop/cart
are the same route cart, with ctx.locale de and the site default. Any
other first segment is part of the path, so /_mallok/p/shop/fr/cart on a
site without fr is a 404, not cart in the default language. The locale
sits after the plugin id, not before /_mallok, so that a plugin can scope a
cookie to /_mallok/p/<plugin_id> and reach every language with it.
A site's locales are settings and can change after a build. So that a route
can never be hidden by a locale added later, a version 2 route may not
start with a segment shaped like a locale code — two letters, optionally
followed by - and two to four more. de, go and my-cart are refused at
build time; cart, checkout and my-orders are fine. Only the first
segment is affected.
A plugin declaring "pluginApi": 1 is routed as before: one segment,
matched literally, with ctx.locale always the site default, and its route
names are not checked against the locale shape. Declaring several segments
or a parameter under version 1 is refused at build time.
Bodies. input.fields holds form fields, or the string-valued top-level
members of a JSON object, as in version 1. input.json is the body of an
application/json request, whole — numbers, booleans, null, arrays and
nested objects included — and undefined for a form or a GET. A JSON body
must be an object or an array; anything else is answered 400 before the
handler runs. Neither is validated beyond that: the handler checks what it
reads.
The route handler validates its own parsed fields.
Rate limiting. A route asks for one of two tiers, each a Workers
rate-limit binding in the site's wrangler.jsonc:
rateLimit |
Binding | In the site template |
|---|---|---|
"strict", or true |
RATE_LIMITER |
10 requests per 60 seconds |
"relaxed" (plugin API 2) |
RATE_LIMITER_RELAXED |
120 requests per 60 seconds |
false, or omitted |
none | — |
- The numbers belong to the site, not to the plugin. A manifest names a
tier; the limit and period are in
wrangler.jsonc, where the site's owner can change them and the runtime can enforce them. Pickstrictfor an action that costs something each time it succeeds — a form that sends email, a checkout — andrelaxedfor one a visitor repeats in normal use, such as changing a cart. - Each route has its own count per visitor. The key is
<plugin-id>:<route path as declared>:<connecting-ip>, so two routes never share a budget even on the same tier, andorders/:orderNois one budget whatever order number is tried. The locale segment is not part of the key. - A site without
RATE_LIMITER_RELAXED— one created before the tier existed, until its owner adds the binding (CLOUDFLARE_RESOURCES.md §4) — guards arelaxedroute withRATE_LIMITERinstead and logs{"event":"rate_limit_binding_missing",…}: tighter than asked for, never unguarded. With no rate-limit binding at all, requests proceed, as before. - What a binding can express (Cloudflare's rate-limit binding documentation, read 2026-10-05): the period is 10 or 60 seconds, nothing longer, so "ten per ten minutes" cannot be configured. Counting is, in Cloudflare's words, permissive and eventually consistent, kept per Cloudflare location, and Cloudflare advises against keying on IP addresses — which an anonymous form has nothing better than. It is best-effort abuse control and must not back billing, stock or any exact quota; a plugin that needs an exact limit counts in its own table.
- A refused request is answered 429 before the body is read or the handler runs.
Pages (plugin API 2). A route that declares "render": "page" and a
layout is a page of the site: its handler returns a view, and the theme's
layout of that name renders it inside the site's own header, navigation and
language switcher. The plugin owns the route and the data; the theme owns
the look.
{ "path": "cart", "method": "GET", "render": "page", "layout": "shop/cart" },
{ "path": "cart/add", "method": "POST", "render": "page", "layout": "shop/cart" }export const routes = {
cart: async (_input: RouteInput, ctx: PluginRequestContext) => ({
title: 'Your cart',
view: { lines: await readCart(ctx), total: '$248.00' },
}),
'cart/add': async (input: RouteInput, ctx: PluginRequestContext) => {
const problem = await addToCart(ctx, input.fields);
if (problem !== null) {
return { status: 422, view: { error: problem } };
}
return new Response(null, { status: 303, headers: { location: '/_mallok/p/shop/cart' } });
},
};- The handler returns a
PluginPageResult—{ view, title?, description?, status?, headers? }— or aResponse, which is passed through unchanged; that is how a POST redirects.viewmust be JSON-serialisable, like arenderDataresult, and reaches the layout asplugin_page(THEME_FORMAT.md §16).headersis forset-cookieand the like. - The page is private and unindexed, always:
Cache-Control: private, no-storeandX-Robots-Tag: noindex, whatever the handler sets./_mallok/is disallowed inrobots.txtas well. It is one visitor's cart, rendered per request; nothing about it is cacheable. - The layout sees the same view a content page does —
site,t,theme,page— withpage.kindpluginandpage.alternatespointing at the same page under each of the site's locales (the locale segment above), so the theme's language switcher works.page.headis empty andrenderDatahooks do not run: the page is the plugin's own. - The layout name is a contract between a plugin and a theme, not with
the core:
shop/cartmeans whatever the plugin's documentation says the view under it contains. A theme that does not provide it leaves the page to a plain built-in layout that names what is missing and lists the view's top-level text, number and boolean values — enough to see the route work, not a usable page.{"event":"plugin_layout_missing",…}is logged per request and the admin's plugin page lists the layouts the theme lacks. - A page route returning something that is neither a view nor a
Response, or a plain route returning a view, is answered 500 with{"event":"plugin_route_bad_result",…}in the log. afterRenderhooks do not run on a plugin page.
The cross-site check, for every plugin. A POST to any plugin route is
refused with 403 when the browser says another site caused it: when
Sec-Fetch-Site is cross-site, or — for a browser that sends no such
header — when Origin names a host other than the one requested.
same-origin, same-site and none pass. A request with neither header
passes: no current browser sends a form or a fetch POST without one, so
it comes from a script or a server, which carries no visitor's cookies and
gains nothing by forging one. A GET is never checked — a link from an order
email or another site has to work — so a handler must not change state on
GET. The check runs before rate limiting, body parsing and the handler.
This is what lets a page route trust a session cookie scoped to
/_mallok/p/<plugin_id>; it does not replace Turnstile for a public form.
Raw bodies (plugin API 2). A route that declares "body": "raw" is for a
webhook: another server calls it and proves who it is with a signature over
the bytes of the body. Parsing those bytes first would destroy what the
signature is over.
{ "path": "stripe-webhook", "method": "POST", "body": "raw" }'stripe-webhook': async (_input, ctx) => {
const payload = await ctx.request.text(); // exactly what was sent
if (!(await verify(payload, ctx.request.headers.get('stripe-signature'), ctx.secrets.signing_secret))) {
return new Response('bad signature', { status: 400 });
}
ctx.waitUntil(followUp(ctx, payload));
return new Response(null, { status: 200 });
},ctx.requestcarries the bytes as they arrived, readable once, as text or as a buffer.input.fieldsis empty andinput.jsonisundefined: the core parsed nothing.- The handler's status code is passed through unchanged. A sender such as Stripe decides from it whether to deliver again — 2xx is delivered, anything else is retried — so answer 400 for a signature that does not verify and 5xx for a failure worth retrying. A handler that throws answers 500.
- No cross-site check. It is not a browser calling. The signature is the only authentication: a raw route that does not verify one is open to anyone.
- A size cap. 256 KiB unless the route declares
maxBytes, up to 1 MiB; a larger body is answered 413 before the handler runs, and a stream of unknown length is cut off as it is read. Stripe's documentation states no maximum event size (read 2026-10-06), so the default is a judgement, not a figure from the sender; raise it for a route that receives large events. - It cannot use Turnstile or be a page route, and both are refused at build
time.
rateLimitis as declared: leave it out for a sender that delivers from a few addresses. - Secrets,
ctx.dbandctx.waitUntilare as for any route.
Every plugin-route response is rewritten to Cache-Control: private, no-store; Cloudflare-CDN-Cache-Control, CDN-Cache-Control and
Surrogate-Control are all forced to no-store, and any Cache-Tag supplied
by a handler is removed. Route caching is not part of the 0.1 contract.
settings: stored in cleartext inplugin_state.settings; the admin generates the form from the schema.secrets: AES-GCM encrypted with a key derived fromMALLOK_SECRETthrough HKDF and stored inplugin_state.secrets, with a fresh random IV on every write (DATA_MODEL §2.7).- A plugin may declare
checkSecrets(added 2026-08-30): a read-only validation function per secret name, behind a "Test" button next to the secret in the admin. The core cannot tell a good third-party key from a bad one; the plugin can. The check must be read-only or safe to repeat, and only the verdict is returned — the secret value never leaves the Worker.
The management API returns only "set" or "not set", and never echoes a
secret value. Rotation is supported: writing a new value overwrites.
SECURITY.md defines the derivation and encoding.
The scheduled hook (§5.5) runs from Mallok's single once-a-minute trigger,
and suits work that is simply repeated. Work that is owed — an email after an
order, a stock count to push somewhere — is a job. Plugin API 2.
export default definePlugin({
manifest: { /* … */ pluginApi: 2 },
jobs: {
// (payload, ctx) => Promise<void>
sync_stock: async (payload, ctx) => {
const { variantId } = payload as { variantId: string };
/* … */
},
},
});A job name is lower-case letters, digits and underscores. A plugin queues its own jobs only:
// By itself: one write.
const jobId = await ctx.enqueue('sync_stock', { variantId }, { runAt });
// Or as part of the change that owes it:
await ctx.db.batch([
ctx.db.prepare('UPDATE p_shop_order SET status = ? WHERE id = ?').bind('paid', id),
ctx.enqueueStatement('send_receipt', { orderId: id }),
]);enqueueStatement returns a prepared statement and does nothing until it is
run. In a batch with the plugin's own statements, the change and the job
are committed together or not at all — an order is never marked paid without
its receipt being owed, and no receipt is owed for an order that was not
saved. The core builds the statement, so a plugin never depends on the job
table's columns; writing that table directly is not part of this contract.
Both refuse, by throwing, a name that is not in the plugin's jobs, and a
payload that is not JSON or is longer than 16 KB as JSON. Queue ids, and read
the rest when the job runs.
What the core promises about a queued job:
- It runs in a later tick of the cron, not in the request that queued it:
expect up to a minute, more when jobs are waiting.
runAtis the earliest time, not an appointment. - At most five plugin jobs run per tick, across all plugins, oldest
runAtfirst, after the site's own housekeeping and scheduled publishing. They share that invocation's CPU budget with each other and with everyscheduledhook (§5.5), so a job should do one small thing. - At least once. A handler can run more than once for the same job — its Worker may stop after the work and before the job is marked done — so it must be safe to repeat. Check what was already done, or key the effect on something stable such as the order's id.
- Retries. A handler that throws is tried again after 2, 4, 8 and 16
minutes: five attempts, the same rule email jobs follow. Each failure is
logged as
plugin_job_failed. After the fifth the job isfailed, stays in the table, is not run again, and is listed under Settings → Advanced → Diagnostics with its last error. - A job whose Worker stopped while it ran is released ten minutes later, and that counts as one of its five attempts: a job that stops the Worker every time runs out of attempts like any other.
- Jobs of a plugin that is switched off wait. They run once it is enabled again. Jobs whose handler no longer exists in the build fail.
There is no interface for retrying a failed job by hand, and none for cancelling a queued one.
A plugin ships no frontend code. It declares a panel and the admin app renders it.
A panel is a page of the admin at /_mallok/app/plugins/<plugin>/<panel>,
listed in the sidebar under Site by its label, between Media and
Plugins; the plugin's card on the Plugins page links to it. A panel with
attachTo (below) is the exception: it is shown only in its kind's editor.
"panels": [
{
"id": "inquiries",
"label": "Inquiries",
"type": "table",
"table": "p_inquiry_inquiry",
"columns": [
{ "field": "created_at", "label": "Received", "type": "datetime" },
{ "field": "name", "label": "Name" },
{ "field": "email", "label": "Email", "type": "email" },
{ "field": "country", "label": "Country" },
{ "field": "status", "label": "Status", "type": "badge" }
],
"filters": [
"status",
"created_at"
],
"detail": ["message", "company", "phone", "source_path", "user_agent"],
"actions": [
{ "id": "mark_replied", "label": "Mark replied" },
{ "id": "mark_spam", "label": "Mark spam" },
{ "id": "export_csv", "label": "Export CSV", "type": "download" }
]
}
]Ids declared in actions correspond to keys in the implementation passed to
definePlugin:
export const actions = {
async mark_replied(ids: readonly string[], ctx: PluginContext): Promise<Response | undefined> { … },
async export_csv(ids: readonly string[], ctx: PluginContext): Promise<Response> { … },
};Action ids are unique across the whole plugin, because the implementation map is plugin-wide even when the declarations appear in different panels.
Scopes, for API tokens (a signed-in session holds every scope):
| Request | Scope |
|---|---|
| Reading a panel's rows | export — panel rows are plugin business data, guarded like the site export |
A download action |
export |
| Any other action | content:write |
Action parameters (plugin API 2). An action may ask whoever runs it for a few values first — a tracking number, a refund amount:
"actions": [
{ "id": "mark_shipped", "label": "Mark shipped",
"params": {
"tracking_no": { "type": "string", "label": "Tracking number", "required": true },
"carrier": { "type": "select", "label": "Carrier", "choices": ["DHL", "FedEx"] }
} }
]export const actions = {
async mark_shipped(ids, ctx, params) { … params.tracking_no … },
};paramsuses the scalar field types of a record (below),moneyincluded;rowsis not available.- The admin shows a form with those fields before running the action, and the core checks what was submitted against the declaration exactly as it checks a record: a failure is a 422 with messages by field, and the handler is not called.
- The handler receives them as its third argument:
(ids, ctx, params). Only declared parameters arrive; an action that declares none receives{}. A version 1 handler written as(ids, ctx)is unaffected. - A
downloadaction cannot take parameters.
Related rows (plugin API 2). A panel may show, read-only, the rows of a child table that belong to the row being looked at — the lines of an order:
"related": [
{ "id": "lines", "label": "Order lines",
"table": "p_shop_order_line", "foreignKey": "order_id", "orderBy": "position",
"columns": [ { "field": "sku", "label": "SKU" }, { "field": "quantity", "label": "Qty" } ] }
]- They appear in a row's detail view, and in a record's edit form.
- The core reads them as it reads the panel's list: from
table, whereforeignKeyequals the row'sid, the declared columns only, at most 100 rows. The table must carry the plugin'sp_<id>_prefix. GET …/panels/<panel>/related/<id>?parent=<row id>needs theexportscope, like the rows they belong to.
Sorting and search (plugin API 2). Both are declared, and both apply to either type of panel:
"columns": [
{ "field": "name", "label": "Name", "sortable": true },
{ "field": "code", "label": "Code", "sortable": true }
],
"search": ["name", "code"]- A
sortablecolumn's heading orders the list by it, ascending then descending. The list request carriessort=<field>&dir=asc|desc; a field the manifest does not mark sortable is ignored, and the panel'sorderByapplies. Field names never come from the request. searchadds a search box. The request'sqis matched as a substring against each listed column, case-insensitively for ASCII (SQLite'sLIKE), with%and_taken literally. It is a scan of the table, not an index: fine for hundreds of rows, not a search engine.
Editable records (plugin API 2). A panel of "type": "records" is a
list with a form: the admin can create, edit and — if the plugin allows —
delete what it lists.
{
"id": "variants",
"label": "Variants",
"type": "records",
"table": "p_shop_variant",
"columns": [{ "field": "sku", "label": "SKU", "sortable": true }],
"search": ["sku"],
"fields": {
"sku": { "type": "string", "label": "SKU", "required": true },
"status": { "type": "select", "label": "Status", "choices": ["active", "archived"] },
"price": { "type": "money", "label": "Price", "currencies": ["USD", "EUR"] },
"tiers": {
"type": "rows", "label": "Quantity prices", "max": 10,
"fields": {
"from": { "type": "number", "label": "From quantity", "min": 1, "required": true },
"price": { "type": "money", "label": "Unit price", "currencies": ["USD", "EUR"] }
}
}
}
}export const records = {
variants: {
load: async (id: string, ctx: PluginContext) => { … }, // the record, or null
save: async (record: PluginRecordInput, ctx: PluginContext) => { … },
remove: async (id: string, ctx: PluginContext) => { … }, // optional
},
};- The admin never writes to a plugin's table. The list is still read from
table, as for atablepanel, and its rows need anidcolumn. Opening a record callsload; saving callssave; deleting callsremove. How a record maps onto tables — one row, or a parent and its children — is the plugin's business, which is whyloadis the plugin's too. - Field types are the settings vocabulary —
string,text,number,boolean,date,select,string[],color,keyvalue— and two more:money:{ "amount": 9900, "currency": "USD" }.amountis a whole number of the currency's minor units — cents — never a decimal, so nothing is lost to floating point.currencieslists the ISO 4217 codes allowed. The form shows and takes99.00, and converts using the currency's own number of decimal places. Negative amounts need aminbelow zero.rows: an array of objects, each with the declared sub-fields — variants under a product, lines under an order.maxbounds the number of rows (50 when absent). A row's fields are scalar; rows do not nest.
- What
savereceives is already checked against the declaration: required fields are present, aselectholds a listed choice, a number is in range, money is whole minor units in a listed currency, rows are within their limit. An empty optional field arrives asnulland an emptyrowsfield as[]. Only declared fields arrive: anything else in the request is dropped before the handler runs, so a handler can trust the keys.record.idisnullfor a new record. saveanswers{ id }, or{ errors }keyed by field name, for what only the plugin can judge — a SKU already in use. The admin shows each message beside its field. A problem in a row is keyed<field>.<row index>.<sub-field>.loadreturns the values in the shapesavetakes, ornullwhen the record is gone.- Without
remove, the form has no delete. definePluginrefuses a records panel withoutloadandsave, and handlers for a panel that is not one.
Sample data from a starter. A site's starter can carry records for a
records panel (ARCHITECTURE.md §11.1). The first-run wizard submits each to
the panel's save exactly as the form would — id is null, values are
checked against fields first, attachedTo is the owning document's
translation group — so a handler needs nothing extra to support it, and
cannot tell the difference. An { errors } result or a thrown error is
reported to the operator and the import carries on.
Attached to content (plugin API 2). A records panel can belong to content of one kind, and is then edited where that content is edited:
{
"id": "variants", "type": "records", "table": "p_shop_variant",
"attachTo": { "kind": "product" },
…
}- In the admin the panel appears under the editor of every
product, listing the records of the item that is open, and nowhere else: the plugins page only says where to find it. - Records are keyed by the item's translation group, not by its id: a
product's variants are the same whichever language of it is open. The
panel's table needs a column holding the group —
translation_group, or the name given asattachTo.column— which is what the list filters on. saveis told which item:record.attachedTois{ translationGroup, kind }. The core has checked that content of that kind with that group exists; a request naming none, or another kind's, is refused before the handler runs. For a panel that is not attached it isnull.- A new item has no group until it is first saved, so the panel appears once it has been.
- The panel's records are saved by its own Save, independently of the item's Publish.
- Cleaning up is the plugin's job, through
onContentDelete(§5.7): when the hook reportslastInGroup, the item is gone in every language and its records should go. The core never deletes from a plugin's table. A plugin with an attached panel and no delete hook leaves orphans.
| Request | Scope |
|---|---|
GET …/panels/<panel>/records/<id> |
export, like the list |
POST …/records, PUT …/records/<id>, DELETE …/records/<id> |
content:write |
Validation failures answer 422 with { "error", "errors": { <field>: <message> } }. A signed-in session's writes carry the CSRF token, as every
write does.
The inquiry list, and any future order list, is a panel of this kind. This mechanism exists so that a plugin never needs to write React or Preact code — the moment a plugin can inject frontend code into the admin, both the admin's size budget and its security boundary are gone.
interface EmailMessage {
readonly to: string;
readonly subject: string;
readonly html: string;
readonly text: string;
readonly replyTo?: string;
}The only implementation in 0.1 is Resend, called through its HTTP API with
fetch and no SDK (TECH_STACK §5). Delivery records and retries live in
the core's job table.
sendEmail is an internal function boundary, not a provider abstraction
(ARCHITECTURE §17). 0.1 builds no adapter for a mail provider it might use
one day.
The Resend key and the sender address are site settings (Settings →
Email in the admin, PUT /_mallok/api/settings/email), entered once and used
by every plugin. A plugin declares neither. When a message is attempted — at
send time, not when it is queued — the core picks:
| First choice | Otherwise | |
|---|---|---|
| Key | The calling plugin's own resend_api_key secret, when one is stored and can be decrypted |
The site's key |
| Sender | The calling plugin's from_address setting, when it is a non-empty string |
The site's sender |
The plugin-level entries exist for two reasons: a plugin written before site
email keeps working with the key it already stores, and a plugin may send from
an address of its own (the official inquiry plugin keeps an optional
from_address for that). A new plugin should declare no resend_api_key
secret. With no usable key, or no sender, the job fails with a message that
says which is missing and is retried on the usual schedule, so a message
queued shortly before the operator enters the key is still delivered.
POST /_mallok/api/settings/email/check asks Resend whether the stored key
works and returns only the verdict. Both endpoints need settings:write; the
key is never returned by any endpoint.
A plugin builds its own messages, with two helpers exported from
mallok/worker for that purpose:
import { escapeHtml, renderTextTemplate } from 'mallok/worker';
escapeHtml(value: string): string;
renderTextTemplate(source: string, data: Readonly<Record<string, unknown>>): Promise<string>;renderTextTemplate renders a plain-text Liquid template — typically one the
operator edits in the plugin's settings — with the same restricted engine
themes use (strict filters, own properties only, bounded parsing and
memory). Its output is text and is not HTML-escaped. An HTML body is the
plugin's own markup, and every value in it, rendered template text included,
goes through escapeHtml; that is what keeps what a buyer typed from becoming
markup in the email. The official inquiry plugin does exactly this
(src/plugins/inquiry/emails.ts), and a broken operator template falls back
to built-in text rather than losing the message.
A plugin that owns portable business data implements exportFiles:
export async function exportFiles(
ctx: PluginContext,
): Promise<readonly PluginExportFile[]>;Each result is { path, text }. Paths use forward slashes and must be
relative and portable: no absolute or drive path, backslash, dot or empty
segment, control character, reserved Windows filename, trailing dot or space,
or overlong segment. Case-only and canonically equivalent Unicode names count
as the same path. A plugin cannot replace a core export file or another
plugin's file, and one invalid entry rejects that plugin's entire contribution
rather than leaving half of it in the manifest. Cross-plugin conflicts are
resolved deterministically by plugin id.
The manifest names every plugin whose export failed. Both the CLI and the browser refuse to produce a backup when that list is non-empty, so an archive without inquiries or other plugin-owned data cannot be reported as complete.
What plugin.json declares for the operator — the plugin's description,
setting and secret labels, panel, column and action labels, field labels
and help — is English. A plugin may give it in other interface languages
with adminCatalogs, keyed by language tag; by convention each catalog is
a file admin/<ui-locale>.json beside plugin.json:
import adminZhCn from './admin/zh-CN.json';
import manifest from './plugin.json';
export const shop = definePlugin({
manifest,
adminCatalogs: { 'zh-CN': adminZhCn },
// …
});A catalog is a flat map from where a word is declared to that word:
| Key | Replaces |
|---|---|
name, description |
The manifest's own |
settings.<key>.label, .help; groups.<group> |
A setting's words; a settings group |
secrets.<key>.label |
A secret's label |
scripts.<src>.purpose |
A client script's purpose |
panels.<panel>.label |
A panel's label |
panels.<panel>.columns.<field> |
A column's label |
panels.<panel>.names.<field> |
A field's name where the panel shows the name, not a column label: a filter, the detail view, the search box |
panels.<panel>.values.<field>.<value> |
How a value of a badge column reads (new, replied); any value of a badge column may be named |
panels.<panel>.empty |
What the panel says while it has no rows, such as where its rows come from ("No inquiries yet. They appear here when a visitor sends the form on your contact page."). Words with no declaration of their own: without it the admin says "Nothing here yet." The inquiry plugin carries it in en too (ADMIN_SIMPLE.md §6.3) |
panels.<panel>.fields.<field>.label, .help; .fields.<field>.fields.<inner>.label, .help; panels.<panel>.groups.<group> |
A record field's words, a rows field's inner fields', a record field group |
panels.<panel>.actions.<action>.label; .actions.<action>.params.<field>.label, .help |
An action and its parameters |
panels.<panel>.related.<id>.label, .related.<id>.columns.<field> |
A related table and its columns |
- Every key is optional and a missing key keeps the declared English; a plugin without catalogs is shown as declared.
definePluginrefuses a catalog that is not an object of strings, that is keyed by something other than a language tag, or that names anythingplugin.jsondoes not declare, so a typo fails the build rather than leaving a label in English.- The admin sends its interface language as
Accept-Language, andGET /_mallok/api/pluginslays the best match over each plugin — an exact tag, then the same primary language.namesandvaluesarrive on each panel beside its declaration. A filter on a field whose values are named is offered as a select of those names; any other filter is typed. - Only words change. Ids, tables, types, a
select'schoicesand a money field's currencies are as declared: a choice is a stored value, and there is no translated label for one yet (ADMIN_I18N_AND_UI.md §9). - It is part of the implementation, not of
plugin.json, so a plugin declaringpluginApi: 1may have one (§13.1). - The official
inquiryplugin shipsadmin/zh-CN.json, and anadmin/en.jsonthat names only its status values, so the status filter can offer them by name; it declarespluginApi: 1.
| Stage | How |
|---|---|
| Discovery | Static imports at compile time; the site passes plugins to createMallok |
| Migration | Runs with the core migrations on a Worker cold start |
| Enable | plugin_state.enabled = 1, immediate |
| Disable | enabled = 0; hooks and routes stop at once, tables and data are kept |
| Removal | Delete the static import and redeploy; 0.1 leaves the plugin's tables intact |
Dynamic import and remote loading are forbidden (TECH_STACK §12). The
plugin registry is a compile-time constant.
A plugin declares through affectsFragmentCache whether it changes stage-one
output:
- a plugin declaring a
beforeRenderhook must set it totrue; - when
true, the plugin's id, version and settings enter therender_cachekey (pluginHashinsrc/worker/render.ts), so changing a setting invalidates every fragment; - a plugin that is
falseand only hasafterRenderstays out of the fragment key, but the edge cache must still be purged — the core purges thesitetag automatically when it is enabled, disabled or reconfigured.
renderData (§5.6) is stage two: what it returns is in the page, never in
the fragment, so it does not enter the render_cache key and a plugin using
only that hook leaves affectsFragmentCache false. Its data is cached with
the page in the edge cache and is refreshed by purging the page.
Every public page carries tags the core chose — site, c:<content-id>,
k:<kind>:<locale>, home:<locale> and so on (ARCHITECTURE §6). A
plugin adds its own from renderData (§5.6), so that when one price changes,
only the pages showing that price are purged.
-
On the page. A tag
treturned incacheTagsby the pluginshopappears asp:shop:t, after the core's tags. Home, list and tag-archive pages are tagged the same way, so a plugin that prints prices on a list returns the tag of every item it printed. -
Purging.
ctx.purgeTags(['t'])purgesp:shop:t. A plugin can purge only its own namespace, andsite. Whatever it passes is prefixed with its own id, soctx.purgeTags(['c:123'])asks forp:shop:c:123— a tag no page has — rather than the core'sc:123, and another plugin'sp:other:tcannot be named at all.siteis passed through, for a change that can affect any page. This applies to every plugin, whichever API version it declares (§13.3). -
What a tag may be. Cloudflare's rules, read 2026-10-05 (purge by tags): printable ASCII, no spaces, no commas, compared without regard to case; the whole header at most 16 KB; a tag in a purge call at most 1,024 characters, prefix included. A tag that breaks a rule, or would overflow the header, is left off the page and
{"event":"cache_tag_rejected","tag":…,"reason":…}is logged; the core's tags come first, so they are never the ones to go. AcacheTagsthat is not an array of strings is ignored as a whole andcache_tags_droppedis logged. Neither stops the page from being cached. -
What purging costs. One purge call carries at most 100 tags; more are sent as several calls. Calls within two seconds are coalesced into one. On the Free plan Cloudflare allows 5 purge calls a minute with a burst of 25, shared by every zone of that plan on the account (purge limits, read 2026-10-05, unchanged 2026-10-25). A bulk change should purge
siteonce, not a tag per row. WithoutCF_API_TOKENandCF_ZONE_IDnothing is purged and pages expire by their TTL, as for the core's own purges. -
What the call tells you (Task 47).
ctx.purgeTagsresolves, after the two-second window, to aPurgeOutcome:{ attempted, ok, status? }.attempted: falsemeans the site has no purge token.attempted: true, ok: falsemeans the pages are still cached: Cloudflare refused (statusis its HTTP status; 401 or 403 usually means the token lacks Zone → Cache Purge → Purge) or could not be reached (statusabsent). A webhook handler can answer an error then, so the sender retries:const outcome = await ctx.purgeTags(['pricing']); if (outcome.attempted && !outcome.ok) { return new Response('purge failed', { status: 503 }); }
The failure is logged as
purge_failedwithsource: "plugin:<id>"and shown under Settings → Advanced, whatever the plugin does with it. The purge happens whether or not the plugin waits for it: the core keeps it alive past the end of the request. Only a success counts as one: a reply that is not Cloudflare's JSON saying"success": trueis a failure. Checked on a deployed site on 2026-10-25: a raw-body route's purge of its own tag reached a cached page 3.6 seconds after the request. -
A page a failed
renderDatahook kept out of the cache carries no tags; there is nothing to purge.
Declaring this wrongly means changing a setting and still seeing old content.
At install the core rejects a plugin that declares beforeRender alongside
affectsFragmentCache: false.
Pre-bundling the official plugins is only possible while the total fits
(ARCHITECTURE §12). The rules:
- Every added plugin must come with a before-and-after
pnpm bundle:sizein the commit. - A plugin must not introduce a second implementation of something the render layer already has — a second Markdown parser, a second validation library.
- A plugin must not introduce a vendor SDK; call the API with
fetch. - The current baseline is 202.65 KiB gzip for the Worker, measured as wrangler's Total Upload, against Mallok's own 3 MiB gzip render-path budget. Cloudflare's limit is 64 MiB uncompressed on either plan.
0.1 has one (PRODUCT_VISION §6):
inquiry — the heart of 0.1's acceptance. The path is in
ARCHITECTURE §13:
A native <form> on the product page (hidden content_id and locale; a honeypot field; the Turnstile widget)
→ POST /_mallok/p/inquiry/submit
→ zod validation → honeypot and submission-timing checks → Turnstile verification → rate limit
→ write p_inquiry_inquiry (with request.cf.country, the user agent, ip_hash)
→ two jobs: notify the site owner (Reply-To is the buyer's address) and auto-acknowledge the buyer (template chosen by locale)
→ attempt delivery immediately; the cron retries failures
→ 302 to that locale's thank-you page, which is cacheable
It is the only thing in 0.1 permitted to inject client-side JavaScript — the
Turnstile script (PRODUCT_VISION §5.6).
- No plugin sandbox, and no pretence that one exists.
- No plugin marketplace runtime, no remote installation, no upload-and-install in the browser. That is a 1.0 direction, and it will be a marketplace of source too.
- Plugins may not inject frontend code into the admin; declarative panels only.
- Plugins may not register Liquid filters or tags, which would break through the theme security boundary.
- Plugins may not add a Cron Trigger; a site has exactly one.
- No KV, Queues or Durable Objects for plugins (
TECH_STACK §12). - No inter-plugin dependency declarations or version solving. With one official plugin in 0.1, that would be premature abstraction.
- Status: in progress (phase six of
docs/IMPLEMENTATION_PLAN.md, Tasks 18–35). Each row below is filled in when its task lands; until then a row names what is planned, not what exists, and nothing marked planned may be relied on.
Version 2 exists for site-level plugins such as the Nundar shop plugin, which ship as source inside a site. Every addition is generic: none of them knows about prices, orders or stock, and each must make sense for any plugin — an inquiry cart or a booking plugin as much as a shop.
- Version 2 only adds. A new hook, a new key in a route or panel
declaration, a new member on a context object. Nothing defined by version 1
changes meaning or goes away, so a plugin declaring
pluginApi: 1, or omitting it, runs unchanged on a build that supports 2. The officialinquiryplugin is the standing proof and is not edited to pass. - A plugin declaring
pluginApi: 2is refused at build time by a build that supports only 1 — "This plugin needs plugin API 2; this build supports 1" (src/core/plugin.ts) — rather than degrading silently. - A security check added for every plugin, whichever version it declares, is listed in §13.3 and in the release's upgrade notes. Tightening a check is the one kind of change that can affect a version 1 plugin, and it is never made silently.
- The build's supported version (
PLUGIN_API_VERSIONinsrc/core/plugin.ts) is 2 as of Task 22 (renderData), the first addition that changes what aplugin.jsonmay declare. Releases up to0.1.0-rc.9support 1 and refuse a plugin declaring 2. Additions that are plain exports, such as the public helpers, need no declaration and are usable under version 1. - A version 2 hook needs a version 2 declaration. A manifest that lists
renderDataand declares"pluginApi": 1is refused at build time: "The renderData hook needs plugin API 2; this plugin declares 1." A manifest that omitspluginApigets the build's own version, as before. - The rows of §13.2 still marked Planned are not in this build. A plugin declaring 2 is accepted from here on, so the table, not the version number, says what can be relied on until the phase closes.
| Addition | Where it is documented | Task | Status |
|---|---|---|---|
Public helpers: escapeHtml, renderTextTemplate |
§7.6 and the mallok/worker exports |
20 | Done |
Site-level email settings used by ctx.sendEmail |
§7.6 | 21 | Done |
renderData: plugin data read while rendering a page |
§5.6, §6; THEME_FORMAT.md §7.9 |
22 | Done |
renderData adds offers to the page's Product structured data |
§5.6; SEO_PERFORMANCE.md §5 |
41 | Done |
Plugin cache tags (p:<plugin-id>:<tag>) |
§5.6, §9.1 | 23 | Done |
Multi-segment routes with parameters, a locale segment, input.json |
§7.2 | 24 | Done |
Rate-limit tiers (rateLimit: "strict" | "relaxed"), counted per route |
§7.2; CLOUDFLARE_RESOURCES.md §4 |
25 | Done |
Plugin pages rendered through theme layouts (render: "page") |
§7.2; THEME_FORMAT.md §16 |
26 | Done |
onContentSave called on every save path; onContentDelete |
§5.4, §5.7 | 27 | Done |
Editable records panels with money and rows fields, sorting, search |
§7.5 | 28 | Done |
Panels attached to the content editor (attachTo) |
§7.5 | 29 | Done |
Raw-body routes (body: "raw") |
§7.2 | 31 | Done |
| Action parameters and related rows | §7.5 | 32 | Done |
ctx.t in afterRender: the theme's language pack for the page (any API version) |
§5.3; THEME_FORMAT.md §10 |
42 | Done |
Sample data for a plugin from a site's starter, through a records panel's save |
§7.5; ARCHITECTURE.md §11.1 |
34 | Done |
Per-plugin isolation of scheduled, and a job API (ctx.enqueue, ctx.enqueueStatement, jobs) |
§5.5, §7.4 | 33 | Done |
ctx.purgeTags resolves to a PurgeOutcome (was unknown) |
§9.1 | 47 | Done |
ctx.site.prefixDefaultLocale and the localePrefix(locale, site) helper |
§7, ARCHITECTURE.md §9 |
49 | Done |
Admin catalogs (adminCatalogs): declarations in the operator's language (any API version) |
§7.8; ADMIN_I18N_AND_UI.md D5 |
— | Done |
Theme-side changes in the same phase are documented in THEME_FORMAT.md:
layouts for plugin pages (§16, Task 26), which are optional, and the script
check for themes that declare clientScripts (§9, Task 30, done), which is a
tightening — a theme that declared one script and also carried inline script
or an on…= attribute no longer builds. The five official themes pass
unchanged.
| Check | Effect on a version 1 plugin | Task | Status |
|---|---|---|---|
Reading a panel's rows requires the export scope (§7.5) |
A token without export gets 403 instead of the rows; the admin's own session is unaffected |
19 | Done, ships as 0.1.0-rc.8 |
ctx.purgeTags purges only the calling plugin's own tags, and site (§9.1) |
A plugin that purged a core tag such as c:<id> or home:<locale> no longer does: the tag it names is now inside its own namespace. The official inquiry plugin never calls purgeTags |
23 | Done |
onContentSave is called, as §5.4 always said (§5.4) |
A version 1 plugin that declares the hook now has it run on every save: it can rewrite what is stored and refuse saves, where before it silently did nothing | 27 | Done |
A cross-site POST to any plugin route is refused with 403 (§7.2) |
A same-site form, such as the inquiry form, still submits; a request with neither Sec-Fetch-Site nor Origin is allowed. A form on another site that posted to a plugin route — an inquiry form embedded on a partner's page — no longer works |
26 | Done |
{ "id": "inquiry", // [a-z][a-z0-9-]*; also the table prefix and the route prefix "name": "Inquiry form", "version": "1.0.0", "description": "Product inquiry form with spam protection and email delivery.", "pluginApi": 1, // the version of this contract "hooks": ["afterRender", "onContentSave", "scheduled"], "routes": [ { "path": "submit", // actually /_mallok/p/inquiry/submit "method": "POST", "turnstile": true, // the core performs the server-side siteverify "rateLimit": true // a site binding; key is plugin id + route + IP (§7.2) } ], "settings": { // stored in cleartext in plugin_state.settings "recipient": { "type": "string", "label": "Recipient email", "required": true }, "from_address": { "type": "string", "label": "From address" }, // optional; §7.6 "autoreply": { "type": "boolean", "label": "Send auto-reply", "default": true }, "block_countries": { "type": "string[]", "label": "Blocked countries" } }, "secrets": { // AES-GCM encrypted into plugin_state.secrets "turnstile_secret": { "label": "Turnstile secret key" } }, "panels": [ /* §7.5 */ ], "affectsFragmentCache": false, // see §9 "clientScripts": [ { "src": "https://challenges.cloudflare.com/turnstile/v0/api.js", "purpose": "Turnstile bot protection", "bytes": 0 } ] }