Skip to main content

Crate portaki_sdk_macros

Crate portaki_sdk_macros 

Source
Expand description

Proc-macros that declare Portaki Wasm module metadata at compile time.

Each macro prepends an invisible const block (via emit::write_emission) that writes a JSON fragment when OUT_DIR is set during cargo build — Cargo sets it only for a crate with a build script, so a module keeps a build.rs (fn main() {} is enough). A wasm32 build without one fails at portaki_module! with that advice. Fragments land under:

{OUT_DIR}/portaki-emissions/{kind}-{sanitized_key}.json

where OUT_DIR is Cargo’s per-crate build output directory (e.g. target/debug/build/<crate-hash>/out/ for host builds, or the analogous path under target/wasm32-unknown-unknown/ for Wasm targets).

§Build pipeline

  1. Module source uses these macros (typically via portaki_sdk::prelude::* re-exports).
  2. cargo build --target wasm32-unknown-unknown expands macros and writes emission files.
  3. portaki build calls find_emissions_dir, which picks the most recently modified portaki-emissions directory under target/, then collect_emissions + generate_manifest merge fragments into target/portaki/manifest.json.
  4. portaki lint validates capability ids against the host catalog (portaki_sdk::capability::ALL / is_known), i18n keys, and manifest shape.

A portaki.module.json catalog at the module root can override or supplement emissions; if neither emissions nor a catalog exist, portaki build fails.

§Emission kinds

Macrokind fieldFilename pattern
portaki_modulemodulemodule-{id}.json
entityentityentity-{StructName}.json
entity_indexesentity_indexesentity_indexes-{EntityName}.json
surfacesurfacesurface-{context}_{id}.json
queryqueryquery-{name}.json
commandcommandcommand-{name}.json
paramsparamsparams-{TypeName}.json
configconfig (+ query legacyConfig, command legacyConfigAdopted)config-{StructName}.json
email_varsemail_vars (+ query emailContext)email_vars-emailContext.json
email_blocksemail_blocks (+ query emailContext)email_blocks-emailContext.json
event_handlerevent_handlerevent_handler-{event_type}.json
capabilitycapabilitycapability-{id}.json
connectorconnector_builtinconnector_builtin-{builtin}.json
custom_connectorconnector_customconnector_custom-{id}.json
connector_opconnector_opconnector_op-{fn_name}.json

entity_indexes emissions are written for Atlas/migration tooling; they are not merged into manifest.json today (only entity field metadata is).

§Wasm runtime code generation

portaki_module additionally emits Extism export shims (portaki_query, portaki_command) and a __getrandom_v03_custom hook when target_arch = "wasm32".

query, command, and surface emit inventory::submit! handler registrations that wire manifest operation names to the annotated Rust function via JSON dispatch — a HandlerRegistration on wasm32, a HandlerDeclaration (with the handler’s kind and surface context) on native targets, where the test-utils conformance battery reads it.

Macros§

bundle_text
A text of the module’s own bundles, in every language they have — an I18nText.
portaki_module_decl
Function-like module declaration (portaki_module!(…)).

Attribute Macros§

capability
Declares a required or optional host capability dependency.
choice
A unit enum a declared field picks from (unstable). label = "rule.status": a value’s label is the bundle key rule.status.<value>; #[icon(IconName::X)] on a variant gives its icon. Writes the derives, portaki_sdk::resource::Choice, and the values for the manifest.
collection
A collection the SDK stores (unstable): #[collection(name = "rules", item = Rule, meta = Display, max = 30, import)] on a unit struct. Generates load / save, the updateConfig command (host form), importRows (with import), the host query readRows (with read: the rows as declared, for the platform’s guest assistant — only on rows the guest sees, never on a record), publishReadiness (unless readiness = false), the PortakiResource entity and the manifest’s resources[] entry.
command
Declares a mutating gateway command operation.
config
Declares the module’s host configuration: the struct is the schema, the platform the store.
connector
Declares use of a built-in platform connector (manifest reference only).
connector_op
Declares one HTTP operation on the most recently emitted custom connector, or a validator stub.
custom_connector
Declares a custom HTTP connector implemented by the module.
email
Declares an email the command sends, so the manifest lists it without anyone writing JSON.
email_blocks
Declares the blocks a module adds to Portaki stay emails, per email.
email_vars
Declares the variables a module gives Portaki guest emails, per template, on the function that computes them.
entity
Declares a persistent entity schema for Atlas and host::repo.
entity_indexes
Declares repository indexes for an entity (Atlas spatial/field indexes).
event_handler
Declares a subscription to a platform event type.
item
A row type of a declared collection (unstable), or with meta its settings. Each #[field(label = "…", required, max_chars = N, between(a, b), description = "…")] is declared: kind from the Rust type (I18nText, String, bool, numbers, a #[choice] enum; kind = "time_range" on a String). Adds id, the derives, #[serde(default)], and portaki_sdk::resource::Item (or Meta). key = "title": the natural key an import dedupes on.
nav
Declares a host dashboard entry that no surface renders.
params
Describes the arguments of a query or command, so tooling can offer a form for them.
portaki_module
Declares module identity and bootstraps Wasm exports.
query
Declares a read-only gateway query operation.
record
A record the SDK stores (unstable): what a guest deposits during a stay and the host follows. #[record(name = "reports", item = Report, status = ReportStatus, due_hours = 24, task_title = "…", task_done = "…", hooks)] on a unit struct. Generates list / for_stay / get, the commands submit (guest), add, setStatus, note, the query listForStay, the timeline contract when due_hours is set, and the entity. With hooks, the module implements portaki_sdk::resource::RecordHooks (guard, on_created, on_note).
surface
Declares a host or guest SDUI surface renderer.
wire
Marks a struct or enum as a Portaki wire JSON DTO (gateway / SDUI / events / email).