surma
8d3c163992
Part 1 fixes: complete stdout writes, buffered stdin, Rust type names in schemas, enum variant docs, -32603 for serde errors in handlers, crate docs and modules. End-to-end check of a generated consumer through a fake core.
66 lines
2.5 KiB
Rust
66 lines
2.5 KiB
Rust
//! Write single-threaded WASI plugins for Sausage.
|
|
//!
|
|
//! Each core call starts a process. Keep its initial value cheap to construct.
|
|
//! Declare documented parameter and result types with [`macro@schema`].
|
|
//! Declare methods with [`macro@rpc`], then serve them with [`run`].
|
|
//!
|
|
//! ```no_run
|
|
//! use sausage_plugin::{rpc, schema, Result};
|
|
//! struct Calculator;
|
|
//! /// The numbers to add.
|
|
//! #[schema]
|
|
//! struct AddParams {
|
|
//! /// The first number.
|
|
//! a: i32,
|
|
//! /// The second number.
|
|
//! b: i32,
|
|
//! }
|
|
//! #[rpc]
|
|
//! impl Calculator {
|
|
//! /// Add two numbers.
|
|
//! fn add(&self, p: AddParams) -> Result<i32> { Ok(p.a + p.b) }
|
|
//! }
|
|
//! fn main() { sausage_plugin::run(Calculator); }
|
|
//! ```
|
|
//!
|
|
//! Use [`call`] for outgoing calls. Await its builder for the JSON result.
|
|
//! Use `detach()` to detach the child and `on_notify(f)` to receive progress.
|
|
//! Use [`Ctx::notify`] to report progress to your caller.
|
|
//! Use [`Ctx::exit_after_response`] to end the process after the response.
|
|
//!
|
|
//! [`background`] keeps the process alive while a task runs.
|
|
//! At stdin EOF, pending calls fail and the optional [`macro@on_stop`] hook runs.
|
|
//! The stop hook can write files and send notifications, but cannot make calls.
|
|
//! [`macro@on_retired`] handles `rpc.retired` after an upgrade.
|
|
//!
|
|
//! Use [`lock`] before shared state changes. A guard releases its lock on drop.
|
|
//! `try_now()` returns a guard whose `held()` method reports success.
|
|
//! `keep()` retains a lock until process exit.
|
|
//! [`state_dir`], [`write_atomic`], and [`pid`] provide filesystem and identity helpers.
|
|
//! Use [`macro@test`] for async tests. Native tests fail clearly without a core transport.
|
|
//! [`macro@import`] reads `imports/<provider>.json` and generates a private typed client.
|
|
//! Its functions return [`TypedCall`] builders with progress and detach options.
|
|
//! Declare endpoint types with `#[rpc(endpoints(control = Control))]`.
|
|
//! [`listen`] publishes a declared interface at an endpoint file.
|
|
//! [`connect`] verifies its owner before it returns an [`Endpoint`].
|
|
//! Endpoint calls report progress through [`EndpointCall::on_notify`].
|
|
//! Log with `eprintln!`. Stdout belongs to JSON-RPC.
|
|
#![warn(missing_docs)]
|
|
mod discovery;
|
|
mod endpoints;
|
|
mod error;
|
|
mod helpers;
|
|
mod imports;
|
|
mod lines;
|
|
mod transport;
|
|
pub use discovery::*;
|
|
pub use endpoints::*;
|
|
pub use error::*;
|
|
pub use helpers::*;
|
|
pub use imports::*;
|
|
#[doc(hidden)]
|
|
pub use inventory;
|
|
pub use sausage_plugin_macros::{import, on_retired, on_stop, rpc, schema, test};
|
|
pub use transport::*;
|
|
pub use {schemars, serde, serde_json};
|