1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
//! Write Simple platform actions in Rust.
//!
//! ```no_run
//! use simpleplatform_sdk::prelude::*;
//!
//! #[derive(Deserialize)]
//! struct Input {
//! customer_id: String,
//! }
//!
//! #[derive(Deserialize)]
//! struct Open {
//! invoices: Vec<Invoice>,
//! }
//!
//! #[derive(Deserialize)]
//! struct Invoice {
//! amount: f64,
//! }
//!
//! #[derive(Serialize)]
//! struct Output {
//! customer_id: String,
//! total: f64,
//! }
//!
//! const OPEN_INVOICES: &str = r#"
//! query Open($id: ID!) {
//! invoices: crm__invoice(where: {customer_id: {_eq: $id}, status: {_eq: "open"}}, limit: 500) {
//! amount
//! }
//! }"#;
//!
//! fn main() {
//! simple::run(|request: Request<Input>| {
//! let open: Open =
//! simple::graphql::query(OPEN_INVOICES, json!({ "id": request.data.customer_id }))?;
//!
//! Ok(Output {
//! total: open.invoices.iter().map(|invoice| invoice.amount).sum(),
//! customer_id: request.data.customer_id,
//! })
//! })
//! }
//! ```
//!
//! No lifetimes, no `async`, no `unsafe`, no envelope, no context threading, one
//! import line.
//!
//! # Describing an action
//!
//! What an action is, and what its input looks like, is written where the code
//! is — in the doc comments and on the members themselves. There is nothing to
//! keep in step by hand.
//!
//! Three tags describe the action, written with `///` in the doc comment above
//! the handler — the same comment that carries its description:
//!
//! ```text
//! /// Close a duplicate lead and point it at the record that survives.
//! ///
//! /// The surviving lead keeps its activity; the duplicate is marked closed
//! /// and linked to it, so a later report still reaches both.
//! ///
//! /// @tool
//! /// @short_desc Close a duplicate lead, pointing it at the surviving record.
//! /// @when_use A lead is a duplicate of one already in the system.
//! /// @when_use Two leads share a contact and one should be retired.
//! fn handler(request: Request<Input>) -> Result<Output, Error> { /* ... */ }
//! ```
//!
//! - `@tool` — bare, with no value. It marks the action as one that can be
//! reached as a tool.
//! - `@short_desc` — one line, up to 300 characters. What this is, read in a
//! listing of tools.
//! - `@when_use` — one line, up to 100 characters, written up to ten times. One
//! occasion each, for reaching for this rather than something else.
//!
//! The prose above the tags stays as written, and is the full description.
//!
//! [`Schema`] describes the members, and [the derive's own
//! documentation](Schema) is the reference for it:
//!
//! ```
//! use simpleplatform_sdk::prelude::*;
//!
//! /// The leads to consider.
//! #[derive(Deserialize, Schema)]
//! struct Input {
//! /// The leads to close, by identifier.
//! #[simple(length(min = 1, max = 500))]
//! ids: Vec<String>,
//!
//! /// How far back to look for activity.
//! #[simple(range(min = 1, max = 90))]
//! days: u32,
//!
//! /// Consider only leads whose reference starts here.
//! #[simple(pattern = "^KNOW", length(max = 64))]
//! prefix: Option<String>,
//! }
//! ```
//!
//! `#[derive(Schema)]` generates nothing at all. It makes `#[simple(…)]` legal
//! to write and checks what is written in it, so a bound in the wrong shape is
//! a compile error at the span that holds it rather than a surprise later.
//!
//! Three things are deliberately absent from `#[simple(…)]`, because each has
//! one place already:
//!
//! - **The description** is the doc comment on the member.
//! - **Requiredness** is the type: optional when `Option<T>` or
//! `#[serde(default)]`, required otherwise.
//! - **The property name** is `serde`'s: `#[serde(rename = "…")]` and
//! `#[serde(rename_all = "…")]`.
//!
//! # What this crate takes on so an action does not
//!
//! Rust is a hard language and an action is a small piece of business logic.
//! Resolving that tension is this crate's job:
//!
//! | Rust difficulty | who deals with it |
//! |---|---|
//! | lifetimes and borrows | nothing in the public surface carries one |
//! | `async`, executors, `Pin` | a handler is a plain `fn`; asyncify is a build flag |
//! | `unsafe`, raw pointers, the ABI | `abi.rs`, behind [`host::Transport`] |
//! | `allocate_buffer`, memory | [`run`] owns it |
//! | a panic inside a guest | the panic hook reports a failure envelope |
//! | `Box<dyn Error>` conversion noise | `?` converts anything into [`Error`] |
//! | choosing an error crate | there is one [`Error`], and it ships here |
//! | forgetting to report a result | [`run`] guarantees exactly one `__done__` |
//! | naming a failure the platform can file | [`Code`] is the vocabulary |
//! | writing a mock host in every action | [`testing`] |
//!
//! # The parts
//!
//! - [`run`] — the entry point, and the one report it makes.
//! - [`Request`] — a payload already parsed into your own input type.
//! - [`Error`] and [`Code`] — one error type, one failure vocabulary.
//! - [`Schema`] — the constraints on a member, checked as you write them.
//! - [`testing`] — a host on your own machine, with no wasm anywhere.
//!
//! Five modules reach the platform, and each answers with the type the call site
//! asked for:
//!
//! - [`graphql`] — reading and writing tenant data.
//! - [`http`] — calling a service outside the platform.
//! - [`ai`] — extracting, summarising, transcribing, and the face collection.
//! - [`settings`] — the settings an application was configured with.
//! - [`storage`] — putting a file into the platform's store, and the
//! [`DocumentHandle`] that comes back.
//!
//! They compose in one handler: read the configuration with [`settings`], store
//! a file with [`storage`], read what it says with [`ai`], and write the record
//! with [`graphql`] — one `?` between each, and one [`Error`] out of all of them.
//! `examples/file_expense_receipt.rs` is that action, written out.
//!
//! # Building an action
//!
//! Two artifacts from one source. The default build is for the server, which
//! answers a host call synchronously:
//!
//! ```text
//! cargo build --target wasm32-wasip1 --release
//! ```
//!
//! The `async` build is for the browser, where a host call parks the module and
//! `wasm-opt --asyncify` resumes it:
//!
//! ```text
//! cargo build --target wasm32-wasip1 --release --features async
//! wasm-opt release.ori.async.wasm -Oz --disable-gc \
//! --enable-bulk-memory --enable-bulk-memory-opt --enable-sign-ext \
//! --enable-nontrapping-float-to-int --enable-multivalue --enable-reference-types \
//! --asyncify --pass-arg=asyncify-imports@simple.__call -o release.async.wasm
//! ```
//!
//! The `--enable-*` flags are required: Rust's `wasm32-wasip1` target enables
//! bulk memory and friends by default, and binaryen validates the features it is
//! told about.
//!
//! The two builds declare different imports, which is what the `async` feature
//! selects for you. See `src/abi.rs`.
pub use crate;
pub use crate;
pub use crateTransport;
pub use crate;
/// A stored file, re-exported from [`storage`].
///
/// It is here because it belongs to more than one module: [`storage`] answers
/// with it, [`ai`] reads one, [`graphql`] writes one into a `:document` field,
/// and an action names it in its own output type. The definition and its
/// documentation live in [`storage`].
pub use crateDocumentHandle;
/// Constraints on the members of an action's types, re-exported.
///
/// The derive lives in its own crate, because a crate that defines a procedural
/// macro may export only macros. An action never names that crate: it depends
/// on this one, whose default `derive` feature brings the derive in and puts it
/// here and in the [`prelude`], so `use simpleplatform_sdk::prelude::*;` is
/// still the whole import list. The `simple` helper attribute comes with it.
///
/// An action that writes no constraints turns the feature off with
/// `default-features = false`, and then compiles no procedural macro at all.
pub use Schema;
/// `serde`, re-exported.
///
/// An action normally depends on `serde` itself — the generated `Cargo.toml`
/// lists it — because a `#[derive(Deserialize)]` expands to code that names the
/// crate. This re-export is here for an action that would rather not, and can
/// write `#[serde(crate = "simpleplatform_sdk::serde")]` instead.
pub use serde;
/// `serde_json`, re-exported, for the same reason as [`serde`].
pub use serde_json;
/// Everything an action needs, in one line.
///
/// ```
/// use simpleplatform_sdk::prelude::*;
/// ```
///
/// That brings in [`simple`](crate) itself — so a call reads `simple::run`,
/// `simple::graphql::query` and `simple::http::get` — along with [`Request`],
/// [`Error`], [`Value`](serde_json::Value), the [`json!`](serde_json::json)
/// macro, the two serde derives, and [`Schema`], which carries the
/// `#[simple(…)]` attribute with it.
///
/// # What a module puts here, and what it keeps
///
/// A module's types stay in the module. The exception is a type an action has
/// to write down in order to make the call — the ones that appear in a public
/// signature, which are the options a call takes and the value it answers with:
/// [`ai::Options`], [`ai::TranscribeOptions`], [`ai::FaceSearch`],
/// [`ai::Execution`], [`storage::Source`], [`storage::Target`] and
/// [`DocumentHandle`].
///
/// What a call chooses *inside* one of those is reached through its own module
/// and needs no import, because [`simple`](crate) is already in scope:
/// `simple::ai::Model::Large`, `simple::ai::Participants::Detect`,
/// `simple::storage::Auth::bearer("t-1234")`. A settings read names no type at
/// all, and neither do the five HTTP method functions.
///
/// [`http::Request`] is the one signature type that stays in its module, so that
/// `Request` here always means the request an action was called with. An
/// outbound request is written under the module it belongs to —
/// `use simpleplatform_sdk::http;`, then `http::fetch(http::Request { .. })` —
/// which keeps both names available in the same file, each meaning one thing.