Plugin Capabilities#

Audience. This is the developer-facing reference for the Lesstruct plugin capability manifest and host functions. It references source-tree paths (e.g. internal/plugin/).

If you are a Lesstruct user who has installed the binary and wants to add host function calls to a plugin, use the user-facing snapshot bundled with the lesstruct-plugin-development skill at skills/lesstruct-plugin-development/references/plugin-capabilities.md. It covers the same contract (manifest schema, host functions, security model) but with no source-tree references.

Plugins can request access to host resources (HTTP, database, logging) by declaring them in a capability manifest file placed alongside the .wasm file.

Quick Start#

Create <plugin-name>.manifest next to <plugin-name>.wasm in the plugins/ directory:

1
2
3
4
5
6

name = "my-enrichment-plugin"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
database = ["read:content", "write:content"]

If no .manifest file exists, the plugin gets zero host functions — same as before.

Manifest Reference#

URL Patterns#

URLs are matched using simple prefix matching. Use * as a suffix for wildcards:

1
2
3
4

http = [
    "https://api.example.com/*",         # Match all paths on api.example.com
    "https://jsonplaceholder.typicode.com/todos/1",  # Exact match only
]

• https://api.example.com/* matches https://api.example.com/v1/data, https://api.example.com/foo/bar, etc.
• Patterns are checked in order; the first match wins.
• The trailing * is the only wildcard supported. Regex patterns are not accepted.

Database Permissions#

Database permissions follow the format <operation>:<table>:

The host validates each SQL query to extract the target table name and checks it against the manifest.

Table Access Scope#

Of the 11 tables in the Lesstruct database, only three are grantable to plugins: content_items (normalised to content), media_files (normalised to media), and users. The other eight tables — comments, blocked_emails, failed_login_attempts, verification_tokens, password_reset_tokens, email_update_tokens, soft_deleted_content, and api_keys — are inaccessible to plugins by design. A plugin cannot query or modify them via db_query or db_exec.

Available Host Functions#

HTTP#

Database#

Logging#

Logging functions are always available when any manifest exists — no capability declaration needed.

Result Format#

All host functions return results as JSON at offset 4096 in WASM memory.

Success#

1
2
3
4
5

{
    "status": 200,
    "body": "...",
    "headers": {"Content-Type": "application/json"}
}

Error#

1
2
3
4

{
    "error": "url_not_allowed",
    "message": "URL \"https://evil.com\" not in capability manifest http allowlist"
}

Offset collision. All four data host functions (http_get, http_post, db_query, db_exec) write their result to the same fixed offset (4096). If your plugin calls http_get and then db_query before reading the first result, the second overwrites the first. Read each result before invoking the next host function.

Security Model#

SQL Parser Limitations#

The host uses a hand-rolled substring parser to extract the target table from each query. The parser looks for the first occurrence of FROM, INSERT INTO, UPDATE, or DELETE FROM and reads the first identifier after it.

The parser does not handle:

• Common Table Expressions (WITH ... SELECT).
• Subqueries.
• SQL comments (-- or /* */).
• Quoted identifiers.
• Multi-statement queries.

Write a single explicit SELECT/INSERT/UPDATE/DELETE statement per host function call.

Example: HTTP Enrichment Plugin#

A plugin that calls lesstruct.http_get to enrich a content item during before_save:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

//go:wasmimport lesstruct http_get
func httpGet(urlPtr, urlLen, headersPtr, headersLen uint32) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    url := "https://api.example.com/items/lookup"
    // Write url to WASM memory, call httpGet, read result from offset 4096...
    // Parse JSON, extract a value, set it in customFields, write back to resultBuf.
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}

Manifest:

1
2
3
4
5

name = "http-enrich"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]

Note. The Lesstruct SDK does not currently ship a //go:wasmimport declaration for http_get (or any other host function). The declarations are bundled with the lesstruct-plugin-development skill at references/host-function-imports.go.txt — copy that block into your main.go to use the host functions.

Example: Database Plugin#

A plugin that reads content metadata during a before_save hook:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

//go:wasmimport lesstruct db_query
func dbQuery(
    sqlPtr, sqlLen uint32,
    paramsPtr, paramsLen uint32,
) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    sql := "SELECT COUNT(*) FROM content_items WHERE post_type = ?"
    params := `["product"]`

    // Write SQL and params to WASM memory, call dbQuery, read result from offset 4096...
    resultOffset := dbQuery(sqlPtr, sqlLen, paramsPtr, paramsLen)
    // Parse JSON result from resultOffset...
}

Manifest:

1
2
3
4
5

name = "db-plugin"
version = "1.0.0"

[capabilities]
database = ["read:content"]