salamandr-plugin-sdk 0.3.0

Write Salamandr helpdesk extensions in Rust: safe typed wrappers for every host capability, the fetch_context wire contract, and an in-process mock host for testing.
Documentation
//! The wire contract of `persistent_connect`/`persistent_receive` — the
//! entrypoints a `kind = "chatops"` plugin implements when it declares
//! `scopes.persistent_connection`, the Mattermost/Zulip/Discord-shaped
//! counterpart to the ordinary webhook-delivered `chatops_receive` (see
//! `extwasm.Scopes.PersistentConnection`'s manifest requirement). Register
//! them through the same [`crate::Registry::chatops_op`]/`chatops_ops:`
//! block [`crate::chatops`]'s trio uses — at the wire level this is still
//! "the host calls one of my ops and decodes the answer directly with no
//! `Outcome` wrapper."
//!
//! These types are a field-for-field mirror of
//! internal/extwasm/adapter.go's Persistent* types. Parity is pinned from
//! the Go side by internal/extwasm/sdkcontract_test.go.
//!
//! # The two transports
//!
//! `transport = "long_poll"` needs no [`crate::ws_send`] at all: your
//! `persistent_receive` handler makes its own blocking call via
//! [`crate::http_fetch`]/[`crate::oauth_fetch`] (a long-poll is just an
//! HTTP request a vendor holds open server-side) and returns whatever it
//! found — the host's only job is calling you back-to-back instead of on
//! a schedule tick. `frame` is always `None` for this transport; there is
//! nothing for the host to hand you.
//!
//! `transport = "websocket"` additionally implements `persistent_connect`
//! (called once when the host dials — push your handshake/identify frame
//! via [`crate::ws_send`] from inside it) and reads `frame` on every
//! `persistent_receive` call, which carries one raw inbound frame's text
//! — decode it however your vendor's protocol shapes it, and push any
//! reply frame (a heartbeat ack, say) via [`crate::ws_send`] again. The
//! host owns the actual socket; you never see a connection handle, only
//! frames.

use serde::Deserialize;

pub use crate::chatops::ReceiveResponse as PersistentReceiveResponse;

/// PersistentConnectRequest is what the host passes to
/// `persistent_connect` — deliberately thin, the same reasoning
/// `ScheduledRunInput` documents: this call exists so you can push a
/// handshake frame via [`crate::ws_send`], and `occurred_at` (RFC 3339)
/// is the one useful thing to pass, because a freestanding wasm guest has
/// no clock of its own.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct PersistentConnectRequest {
    pub occurred_at: String,
}

/// PersistentConnectResult is the exact return type `persistent_connect`
/// must have — a bare acknowledgement; the host discards the success
/// payload.
pub type PersistentConnectResult = Result<(), crate::OpError>;

/// PersistentReceiveRequest is what the host passes to
/// `persistent_receive`. `frame` is `None` for `transport = "long_poll"`
/// (your handler makes its own blocking call instead of being handed
/// one) and `Some(text)` for `transport = "websocket"` — the raw inbound
/// frame the host just read off the socket it holds for you.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct PersistentReceiveRequest {
    #[serde(default)]
    pub frame: Option<String>,
}

/// PersistentReceiveResult is the exact return type `persistent_receive`
/// must have — the identical shape `chatops_receive` answers with, so a
/// plugin implementing both transports (or migrating from one to the
/// other) reuses the same note-building code either way.
pub type PersistentReceiveResult = Result<PersistentReceiveResponse, crate::OpError>;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn connect_request_decodes_the_host_input() {
        let req: PersistentConnectRequest = serde_json::from_str(r#"{"occurred_at":"2026-08-14T10:00:00Z"}"#).expect("decode");
        assert_eq!(req.occurred_at, "2026-08-14T10:00:00Z");
    }

    #[test]
    fn receive_request_decodes_a_present_frame() {
        let req: PersistentReceiveRequest = serde_json::from_str(r#"{"frame":"{\"type\":\"hello\"}"}"#).expect("decode");
        assert_eq!(req.frame.as_deref(), Some(r#"{"type":"hello"}"#));
    }

    #[test]
    fn receive_request_decodes_an_absent_frame_as_none() {
        let req: PersistentReceiveRequest = serde_json::from_str(r#"{}"#).expect("decode");
        assert_eq!(req.frame, None);
    }
}