diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 04289fc9..8fce4725 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -252,3 +252,51 @@ jobs: name: oxidezap-${{ matrix.name }} path: ${{ env.ASSET }} if-no-files-found: error + + plugins: + name: Plugin bundle + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ inputs.ref }} + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + toolchain: "1.100.0" + targets: wasm32-unknown-unknown + - name: Build installable plugins + env: + VERSION: ${{ inputs.version }} + run: | + set -euo pipefail + case "$VERSION" in + ""|*[!a-zA-Z0-9._-]*|-*|.*) exit 1 ;; + esac + modules=() + for manifest in examples/*/Cargo.toml; do + plugin="${manifest%/Cargo.toml}" + if [ "$plugin" = examples/template ]; then continue; fi + module="$(cargo xtask plugin build "$plugin")" + modules+=("$module") + done + test "${#modules[@]}" -gt 0 + mkdir -p dist/release + python3 - "dist/release/oxidezap-$VERSION-plugins.zip" "${modules[@]}" <<'PYTHON' + import sys + from pathlib import Path + from zipfile import ZIP_DEFLATED, ZipFile + + modules = [Path(path) for path in sys.argv[2:]] + names = [module.name for module in modules] + if len(set(names)) != len(names): + raise SystemExit("Duplicate plugin module names") + with ZipFile(sys.argv[1], "w", compression=ZIP_DEFLATED) as archive: + for module in modules: + archive.write(module, module.name) + PYTHON + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: oxidezap-plugins + path: dist/release/oxidezap-${{ inputs.version }}-plugins.zip + if-no-files-found: error diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 2040ee3c..a33e57e8 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -67,6 +67,9 @@ jobs: that runs in place, adds its own menu entry and updates through its `.zsync`. `OxideZap.AppImage --cli ...` runs the CLI. + `oxidezap-nightly-plugins.zip` contains optional `.wasm` plugins. + Unpack it and install the modules you want under Settings → Plugins. + The tarballs carry the execute bit. On macOS, clear the quarantine flag before the first run: @@ -83,10 +86,12 @@ jobs: obtains the cross-origin isolation the window needs. `README.md` inside says the rest. NOTES - echo "" >> notes.md - echo "Built from [\`${GITHUB_SHA:0:7}\`](https://github.com/$GH_REPO/commit/$GITHUB_SHA) on $(date -u +"%Y-%m-%d %H:%M") UTC." >> notes.md - echo "" >> notes.md - echo "Verify download integrity with \`sha256sum -c --ignore-missing checksums.sha256\`." >> notes.md + { + echo "" + echo "Built from [\`${GITHUB_SHA:0:7}\`](https://github.com/$GH_REPO/commit/$GITHUB_SHA) on $(date -u +"%Y-%m-%d %H:%M") UTC." + echo "" + echo "Verify download integrity with \`sha256sum -c --ignore-missing checksums.sha256\`." + } >> notes.md # Recreate rather than edit: `gh release edit` cannot move a tag, and # a stale tag would leave the assets pointing at an older commit. gh release delete nightly --yes --cleanup-tag || true diff --git a/.github/workflows/release-check.yml b/.github/workflows/release-check.yml index 0c3fd086..9e98fd0d 100644 --- a/.github/workflows/release-check.yml +++ b/.github/workflows/release-check.yml @@ -42,5 +42,21 @@ jobs: test -s "artifacts/oxidezap-$VERSION-linux-$arch.$suffix" done done - test "$(find artifacts -type f | wc -l)" -eq 12 + python3 - "artifacts/oxidezap-$VERSION-plugins.zip" <<'PYTHON' + import sys + from pathlib import PurePosixPath + from zipfile import ZipFile + + with ZipFile(sys.argv[1]) as archive: + names = archive.namelist() + assert names and len(set(names)) == len(names), names + for name in names: + path = PurePosixPath(name) + assert name == path.name and path.suffix == ".wasm", name + assert name != "template.wasm", name + with archive.open(name) as module: + assert module.read(8) == b"\0asm\x01\0\0\0", name + assert archive.testzip() is None + PYTHON + test "$(find artifacts -type f | wc -l)" -eq 13 (cd artifacts && sha256sum oxidezap-* > checksums.sha256 && sha256sum -c checksums.sha256) diff --git a/README.md b/README.md index c4e64475..3e19b7ac 100644 --- a/README.md +++ b/README.md @@ -223,6 +223,9 @@ history, which is what the in-app "pair again" action does. ## Plugins +Releases include an optional `oxidezap--plugins.zip`. Unpack it and +install the `.wasm` modules you want under Settings → Plugins. + A plugin is a `.wasm` file dropped in `~/.local/share/oxidezap/plugins` — or, in a page running its own session, added under Settings → Plugins, which keeps it in the browser's own storage. Either way it runs inside the daemon — which diff --git a/crates/core/src/plugin.rs b/crates/core/src/plugin.rs index 6fcb4794..d2c8085a 100644 --- a/crates/core/src/plugin.rs +++ b/crates/core/src/plugin.rs @@ -24,6 +24,8 @@ use serde::{Deserialize, Serialize}; pub enum PluginSlot { /// Beside the conversation's name. ChatHeader, + /// Tools shown beside the conversation composer. + Composer, /// A section of the Settings screen. Settings, } diff --git a/crates/daemon/src/plugins/mod.rs b/crates/daemon/src/plugins/mod.rs index 53797d59..c174e4fd 100644 --- a/crates/daemon/src/plugins/mod.rs +++ b/crates/daemon/src/plugins/mod.rs @@ -329,11 +329,15 @@ fn publishing_to(hub: &Arc) -> Sink { /// the rest of the split. Everything a plugin can actually ask for is here, /// written once on top of it. struct Bridge { + hub: Arc, commands: SessionCommands, } impl Commands for Bridge { fn send_text(&self, jid: &str, text: &str, quoted: Option<&str>) -> Outcome { + if !self.hub.connection().is_connected() { + return Outcome::NoSession; + } self.ask(Action::SendText(oxidezap_ipc::SendText { jid: jid.to_owned(), text: text.to_owned(), diff --git a/crates/daemon/src/plugins/native.rs b/crates/daemon/src/plugins/native.rs index cb2f673a..ea8bec89 100644 --- a/crates/daemon/src/plugins/native.rs +++ b/crates/daemon/src/plugins/native.rs @@ -31,8 +31,12 @@ use crate::state::StateHub; pub(super) async fn start(hub: &Arc, commands: SessionCommands) -> Arc { let sink = publishing_to(hub); let account_id = hub.account_id(); - let fallback = (publishing_to(hub), commands.clone()); - tokio::task::spawn_blocking(move || load(sink, commands, account_id)) + let bridge = Arc::new(Bridge { + hub: hub.clone(), + commands, + }); + let fallback = (publishing_to(hub), bridge.clone()); + tokio::task::spawn_blocking(move || load(sink, bridge, account_id)) .await .unwrap_or_else(|e| { // With the daemon's own sink and bridge, not a discarding pair. @@ -43,28 +47,23 @@ pub(super) async fn start(hub: &Arc, commands: SessionCommands) -> Arc // and every command answering `NoSession` — while reporting the // reload as having worked. log::error!("the plugin loader did not finish: {e}"); - let (sink, commands) = fallback; - Arc::new(Plugins::none(sink, Arc::new(Bridge { commands }))) + let (sink, bridge) = fallback; + Arc::new(Plugins::none(sink, bridge)) }) } /// The scan itself, on the blocking thread [`start`] put it on. -fn load(sink: Sink, commands: SessionCommands, account_id: AccountId) -> Arc { +fn load(sink: Sink, bridge: Arc, account_id: AccountId) -> Arc { let Some(dir) = oxidezap_plugin_host::default_dir() else { log::debug!("no per-user data directory, so no plugins"); - return Arc::new(Plugins::none(sink, Arc::new(Bridge { commands }))); + return Arc::new(Plugins::none(sink, bridge)); }; // Not the daemon's `state_dir`: that one prefers XDG_RUNTIME_DIR, which // is cleared on logout, and a permission answer that does not survive a // logout is a prompt asked forever. Scoped to this account: see // `account_state_dir`. let state_dir = account_state_dir(account_id); - Arc::new(Plugins::load( - &dir, - state_dir.as_deref(), - Arc::new(Bridge { commands }), - sink, - )) + Arc::new(Plugins::load(&dir, state_dir.as_deref(), bridge, sink)) } /// See [`super::reload`]. diff --git a/crates/daemon/src/plugins/web.rs b/crates/daemon/src/plugins/web.rs index 34a1f8f5..d0354b1b 100644 --- a/crates/daemon/src/plugins/web.rs +++ b/crates/daemon/src/plugins/web.rs @@ -59,7 +59,10 @@ pub(super) async fn start(hub: &Arc, commands: SessionCommands) -> Arc Plugins::start( modules, Arc::new(Origin::storage_for_account(hub.account_id())), - Arc::new(Bridge { commands }), + Arc::new(Bridge { + hub: hub.clone(), + commands, + }), sink, ) .await, diff --git a/crates/gui/src/app/plugins_ctl.rs b/crates/gui/src/app/plugins_ctl.rs index 1d1451a0..1960beb6 100644 --- a/crates/gui/src/app/plugins_ctl.rs +++ b/crates/gui/src/app/plugins_ctl.rs @@ -6,7 +6,7 @@ //! which needs somewhere to hold what is being typed before anybody commits //! it — and that is what this file is. -use std::collections::HashMap; +use indexmap::IndexMap; use gpui::{App, AppContext as _, Context, Entity, Window}; use gpui_component::input::{InputEvent, InputState}; @@ -58,6 +58,7 @@ impl PluginField { /// oversized setting would disconnect the window. A plugin setting is a /// keyword or a sentence; anything of this size is a mistake either way. const MAX_FIELD_BYTES: usize = 64 * 1024; +const MAX_INACTIVE_COMPOSER_FIELDS: usize = 64; /// A field's address. Two plugins may both call a widget `keyword`, and one /// plugin may draw the same id in two slots. @@ -72,8 +73,8 @@ const MAX_FIELD_BYTES: usize = 64 * 1024; /// selection when Enter is pressed, so a box shared across chats would take /// what somebody typed in one and commit it carrying the other's JID — a /// plugin storing or sending it for the wrong conversation. Switching chats -/// therefore drops what was half-typed in the old one, which is the honest -/// trade: the alternative is not a preserved draft, it is a misdirected one. +/// drops legacy header fields. Composer drafts stay keyed to their own chat +/// until the plugin removes the field, the account changes, or the cache fills. /// /// Which is why the *same* answer `send_plugin_action` gives is taken here /// rather than the selection itself: a Settings action carries no chat, so @@ -83,7 +84,7 @@ const MAX_FIELD_BYTES: usize = 64 * 1024; /// gone for a context it never had. fn key(plugin: &str, slot: PluginSlot, chat: Option<&str>, id: &str) -> FieldKey { let chat = match slot { - PluginSlot::ChatHeader => chat, + PluginSlot::ChatHeader | PluginSlot::Composer => chat, PluginSlot::Settings => None, }; FieldKey { @@ -289,14 +290,39 @@ impl Plugins { } } - // Gone means gone: a plugin that stopped drawing a field has taken it - // back, and holding the entity would keep a subscription alive that - // fires into a widget nobody can see. let live: std::collections::HashSet = wanted .iter() .map(|f| key(&f.plugin, f.slot, chat, &f.id)) .collect(); - self.fields.retain(|k, _| live.contains(k)); + let composers: std::collections::HashSet<_> = wanted + .iter() + .filter(|f| f.slot == PluginSlot::Composer) + .map(|f| (f.plugin.as_str(), f.id.as_str())) + .collect(); + let mut inactive = 0; + self.fields.retain(|key, field| { + if live.contains(key) { + return true; + } + if key.slot != PluginSlot::Composer + || !composers.contains(&(key.plugin.as_str(), key.id.as_str())) + { + return false; + } + let typed = field.state.read(cx).value(); + let keep = typed.len() <= MAX_FIELD_BYTES && typed.as_ref() != field.published; + inactive += usize::from(keep); + keep + }); + let mut excess = inactive.saturating_sub(MAX_INACTIVE_COMPOSER_FIELDS); + self.fields.retain(|key, _| { + if excess == 0 || live.contains(key) { + true + } else { + excess -= 1; + false + } + }); // What is left is what has no box yet. The ones that do are brought // up to date here, and only when the *plugin* moved them: a tree @@ -378,7 +404,9 @@ impl WhatsAppApp { // what it was. Clicking elsewhere, tabbing away and // closing the screen all blur the box, and all of them // now commit what is in it. - InputEvent::PressEnter { .. } | InputEvent::Blur => { + InputEvent::PressEnter { .. } | InputEvent::Blur + if commit_slot != PluginSlot::Composer => + { this.commit_plugin_field(&commit_plugin, commit_slot, &commit_id, cx); } _ => {} @@ -704,6 +732,31 @@ impl WhatsAppApp { cx.notify(); } + fn composer_form(&self, plugin: &str, chat: &str, cx: &App) -> Option { + let surface = self + .plugins(cx) + .iter() + .find(|surface| surface.id == plugin)?; + let mut fields = Vec::new(); + for node in surface.roots_in(PluginSlot::Composer) { + collect_fields(plugin, PluginSlot::Composer, node, &mut fields); + } + let mut values = std::collections::BTreeMap::new(); + let limit = MAX_FIELD_BYTES.checked_sub(chat.len())?; + let mut remaining = limit; + for field in fields { + let value = self + .plugin_field(plugin, PluginSlot::Composer, &field.id, cx)? + .read(cx) + .value(); + remaining = remaining.checked_sub(field.id.len() + value.len())?; + values.insert(field.id, value.to_string()); + } + serde_json::to_string(&values) + .ok() + .filter(|value| value.len() <= limit) + } + /// Tell a plugin one of its widgets was used. /// /// The open conversation goes along only for a slot that has one. A @@ -721,9 +774,25 @@ impl WhatsAppApp { cx: &mut Context, ) { let chat = match slot { - PluginSlot::ChatHeader => self.selected_chat_jid(), + PluginSlot::ChatHeader | PluginSlot::Composer => self.selected_chat_jid(), PluginSlot::Settings => None, }; + let value = if slot == PluginSlot::Composer && widget == PluginWidget::Button { + let Some(form) = chat + .as_deref() + .and_then(|chat| self.composer_form(plugin, chat, cx)) + else { + self.notify_user( + crate::tr!(ComposerPluginFormUnavailable), + super::notices::Tone::Problem, + cx, + ); + return; + }; + Some(form) + } else { + value + }; if let Some(client) = self.client.as_ref() { client.plugin_action(plugin, action, value, chat, slot, widget); } @@ -760,7 +829,7 @@ fn collect_fields(plugin: &str, slot: PluginSlot, node: &PluginNode, out: &mut V } /// The boxes, keyed by what names each one. -type PluginFields = HashMap; +type PluginFields = IndexMap; #[cfg(test)] mod tests { @@ -819,10 +888,10 @@ mod tests { } /// A Settings field is one field whatever is selected, because the action - /// it commits carries no conversation. A header field is one per chat, - /// because the action it commits carries the open one. + /// it commits carries no conversation. Chat tools keep separate fields + /// for each conversation. #[test] - fn only_a_header_field_belongs_to_a_conversation() { + fn chat_tools_fields_belong_to_a_conversation() { let settings = |chat| key("autoreply", PluginSlot::Settings, chat, "keyword"); assert_eq!(settings(Some("a@s.whatsapp.net")), settings(None)); assert_eq!( @@ -830,16 +899,17 @@ mod tests { settings(Some("b@s.whatsapp.net")) ); - let header = |chat| key("autoreply", PluginSlot::ChatHeader, chat, "keyword"); - assert_ne!( - header(Some("a@s.whatsapp.net")), - header(Some("b@s.whatsapp.net")) - ); - assert_ne!( - header(Some("a@s.whatsapp.net")), - settings(Some("a@s.whatsapp.net")), - "and the same id in two slots is still two fields" - ); + for slot in [PluginSlot::ChatHeader, PluginSlot::Composer] { + let chat_field = |chat| key("autoreply", slot, chat, "keyword"); + assert_ne!( + chat_field(Some("a@s.whatsapp.net")), + chat_field(Some("b@s.whatsapp.net")) + ); + assert_ne!( + chat_field(Some("a@s.whatsapp.net")), + settings(Some("a@s.whatsapp.net")) + ); + } } /// The key used to be a formatted string with `/` between its parts. A diff --git a/crates/gui/src/components/plugin_ui.rs b/crates/gui/src/components/plugin_ui.rs index a399362e..8ab44259 100644 --- a/crates/gui/src/components/plugin_ui.rs +++ b/crates/gui/src/components/plugin_ui.rs @@ -12,7 +12,8 @@ //! with a clickable rectangle. use gpui::{ - App, Entity, IntoElement, ParentElement, SharedString, Styled, div, prelude::FluentBuilder as _, + App, Entity, InteractiveElement as _, IntoElement, ParentElement, SharedString, + StatefulInteractiveElement as _, Styled, div, prelude::FluentBuilder as _, rems, }; use gpui_component::ActiveTheme as _; use gpui_component::button::{Button, ButtonVariants as _}; @@ -54,6 +55,51 @@ pub fn slot( .collect() } +pub fn composer(app: &WhatsAppApp, ctx: &PluginContext, cx: &App) -> Option { + let chat = app.selected_chat_jid()?; + if !app + .plugins(cx) + .iter() + .any(|surface| surface.roots_in(PluginSlot::Composer).next().is_some()) + { + return None; + } + let ctx = ctx.clone(); + let metrics = ctx.metrics; + Some( + div() + .px(metrics.space_md()) + .child( + gpui_component::popover::Popover::new(SharedString::from(format!( + "composer-plugins/{chat}" + ))) + .anchor(gpui::Anchor::BottomLeft) + .trigger( + Button::new("composer-plugin-tools") + .label(crate::tr!(ComposerPlugins)) + .ghost() + .small(), + ) + .content(move |_, window, cx| { + let app = ctx.entity.read(cx); + div() + .id("composer-plugin-panel") + .flex() + .flex_col() + .gap(metrics.space_md()) + .w(rems(20.)) + .max_w( + (window.viewport_size().width - metrics.space_xl()).max(gpui::px(0.)), + ) + .max_h(rems(24.)) + .overflow_y_scroll() + .children(slot(app.plugins(cx), PluginSlot::Composer, app, &ctx, cx)) + }), + ) + .into_any_element(), + ) +} + /// One widget and, below it, whatever it holds. fn widget( surface: &PluginSurface, @@ -154,7 +200,9 @@ fn widget( // keyword into, reads back, and leaves — and the plugin goes on // answering the old one. Not drawn over a dead control: a // plugin that stopped cannot be given anything. - let unsaved = live && app.plugin_field_unsaved(&surface.id, slot, &node.id, cx); + let unsaved = live + && slot != PluginSlot::Composer + && app.plugin_field_unsaved(&surface.id, slot, &node.id, cx); div() .flex() .flex_col() diff --git a/crates/gui/src/i18n/catalog.rs b/crates/gui/src/i18n/catalog.rs index 553ec174..50987d6f 100644 --- a/crates/gui/src/i18n/catalog.rs +++ b/crates/gui/src/i18n/catalog.rs @@ -276,6 +276,8 @@ catalog! { Gentle => ("Gentle", "Suave"); TestRingtone => ("Test ringtone", "Testar toque"); Camera => ("CAMERA", "CÂMERA"); + ComposerPluginFormUnavailable => ("This plugin form is unavailable or too large", "Este formulário do plugin está indisponível ou é grande demais"); + ComposerPlugins => ("Chat tools", "Ferramentas da conversa"); CameraModesUnavailable => ("No modes reported for this camera", "Nenhum modo informado para esta câmera"); ResolutionAndFrameRate => ("RESOLUTION AND FRAME RATE", "RESOLUÇÃO E TAXA DE QUADROS"); StopCameraPreview => ("Stop camera preview", "Parar prévia da câmera"); diff --git a/crates/gui/src/views/chat.rs b/crates/gui/src/views/chat.rs index 1c1435a9..5e525990 100644 --- a/crates/gui/src/views/chat.rs +++ b/crates/gui/src/views/chat.rs @@ -51,6 +51,7 @@ pub fn render_connected_view( &plugin_ctx, cx, ); + let plugin_composer = plugin_ui::composer(app, &plugin_ctx, cx); let selected_jid = app.selected_destination_jid(); // Cloned rather than borrowed: building the timeline's rows below needs // the app mutably, and these are handles — a clone is a refcount. @@ -349,6 +350,7 @@ pub fn render_connected_view( offline_recovery, is_own_number, plugin_actions, + plugin_composer, media: media.clone(), }, &message_list, @@ -570,6 +572,7 @@ struct ChatAreaProps<'a> { /// `Context`. Empty when no plugin drew there, which is the ordinary /// case. plugin_actions: Vec, + plugin_composer: Option, media: Option>, } @@ -593,6 +596,7 @@ fn render_chat_area( offline_recovery, is_own_number, plugin_actions, + plugin_composer, media, } = props; let metrics = *layout.metrics(); @@ -665,7 +669,7 @@ fn render_chat_area( if let Some(recovery) = offline_recovery { el.child(render_offline_strip(entity.clone(), recovery, metrics, cx)) } else { - el.children(input_area) + el.children(plugin_composer).children(input_area) } }) .on_drop({ diff --git a/crates/ipc/src/transport.rs b/crates/ipc/src/transport.rs index b9a81e3a..e2d0e6d1 100644 --- a/crates/ipc/src/transport.rs +++ b/crates/ipc/src/transport.rs @@ -291,7 +291,9 @@ use std::path::PathBuf; /// 43 adds the status, sticker-library and composer-media requests, among them /// `PublishStatusMedia`, which an older daemon would refuse as malformed after /// the file had been staged. -pub const PROTOCOL_VERSION: u32 = 43; +/// +/// 44 adds the Composer plugin slot to published widget trees and actions. +pub const PROTOCOL_VERSION: u32 = 44; /// Where the daemon's web bridge listens when nobody says otherwise. /// diff --git a/crates/plugin-abi/src/lib.rs b/crates/plugin-abi/src/lib.rs index 9ad98cce..b6135e5a 100644 --- a/crates/plugin-abi/src/lib.rs +++ b/crates/plugin-abi/src/lib.rs @@ -141,6 +141,7 @@ pub mod imports { pub const KV_GET: &str = "oxi_kv_get"; /// `fn(key, key_len, val, val_len) -> i32`. An empty value deletes. pub const KV_SET: &str = "oxi_kv_set"; + pub const KV_SET_DURABLE: &str = "oxi_kv_set_durable"; /// `fn(delay_ms: i64, token: i64) -> i32` — deliver /// [`super::kinds::TIMER`] carrying `token`, once, after `delay_ms`. /// The host holds a floor under the delay and a ceiling over it: a @@ -492,6 +493,7 @@ pub mod outcome { /// Called at a moment this is not allowed — a declaration outside /// `oxi_init`. pub const STATE: i32 = -5; + pub const UNCONFIRMED: i32 = -6; } /// A string field that is not there at all, distinct from one that is present diff --git a/crates/plugin-abi/src/ui.rs b/crates/plugin-abi/src/ui.rs index 573952c9..225b6fb2 100644 --- a/crates/plugin-abi/src/ui.rs +++ b/crates/plugin-abi/src/ui.rs @@ -120,21 +120,16 @@ pub mod slot { pub const NONE: u8 = 0; /// Beside the conversation's name. The action carries the open chat. pub const CHAT_HEADER: u8 = 1; + /// A panel next to the composer. The action carries the open chat. + pub const COMPOSER: u8 = 2; /// A section of the Settings screen, which is where a plugin's own /// configuration belongs. pub const SETTINGS: u8 = 3; - // 2 is reserved for the composer, which is not drawn yet. It is *not* - // defined here for that reason: a slot the front end silently ignores is - // a button whose author never finds out why it did not appear, which is - // the same failure `ParseError::Misplaced` exists to refuse. A slot - // arrives when something draws it, and arriving is a new constant — an - // addition, not a change. - /// Whether a byte names a slot this format defines. #[must_use] pub const fn is_known(slot: u8) -> bool { - matches!(slot, CHAT_HEADER | SETTINGS) + matches!(slot, CHAT_HEADER | COMPOSER | SETTINGS) } } @@ -943,8 +938,7 @@ mod tests { fn a_slot_this_build_does_not_draw_is_refused() { let mut bytes = vec![FORMAT]; bytes.extend_from_slice(&1u32.to_le_bytes()); - // 2 is reserved for the composer, which nothing renders yet. - bytes.extend_from_slice(&[kind::BUTTON, 2, flags::ENABLED, 0]); + bytes.extend_from_slice(&[kind::BUTTON, 4, flags::ENABLED, 0]); bytes.extend_from_slice(&0u16.to_le_bytes()); for text in ["b", "B", ""] { bytes.extend_from_slice(&(text.len() as u32).to_le_bytes()); @@ -954,7 +948,7 @@ mod tests { parse(&bytes), Err(ParseError::Unknown { kind: kind::BUTTON, - slot: 2 + slot: 4 }) ); } diff --git a/crates/plugin-host/src/guest.rs b/crates/plugin-host/src/guest.rs index bcfb2a08..39007ece 100644 --- a/crates/plugin-host/src/guest.rs +++ b/crates/plugin-host/src/guest.rs @@ -940,44 +940,57 @@ fn link_acting(linker: &mut Linker) -> Result<(), wasmi::Error> { }, )?; - linker.func_wrap( - m, - abi::imports::KV_SET, - |mut c: Caller<'_, Guest>, key: i32, key_len: i32, val: i32, val_len: i32| -> i32 { - if !c.data().allows(abi::caps::STORAGE) { - return abi::outcome::DENIED; - } - // Refused from the *lengths*, before either string is copied. The - // store rejects an oversized entry anyway, but by then the host - // has already allocated and copied up to 64 KiB twice — a cost - // charged as one fixed-price wasm call, so a loop turns a fuel - // budget into allocation traffic the sandbox never sees. - let too_big = |len: i32| !(0..=(crate::kv::MAX_ENTRY as i32)).contains(&len); - if too_big(key_len) || too_big(val_len) { - return abi::outcome::REFUSED; - } - // And the same question about the call as a whole. One entry is - // bounded; the number of them was not, so a loop rewriting one - // key kept nothing and still moved as much memory as it liked — - // the store's budget bounds what is *kept*, and this bounds what - // is copied to keep it. - let spent = &mut c.data_mut().kv_bytes; - let asked = key_len as usize + val_len as usize; - if asked > MAX_KV_BYTES_PER_CALL.saturating_sub(*spent) { - return abi::outcome::REFUSED; - } - *spent += asked; - let [key, value] = match read_strs(&mut c, [(key, key_len), (val, val_len)]) { - Ok(read) => read, - Err(code) => return code, - }; - if c.data_mut().kv.set(&key, &value) { - abi::outcome::ACCEPTED - } else { - abi::outcome::REFUSED - } - }, - )?; + for (name, durable) in [ + (abi::imports::KV_SET, false), + (abi::imports::KV_SET_DURABLE, true), + ] { + linker.func_wrap( + m, + name, + move |mut c: Caller<'_, Guest>, + key: i32, + key_len: i32, + val: i32, + val_len: i32| + -> i32 { + if !c.data().allows(abi::caps::STORAGE) { + return abi::outcome::DENIED; + } + // Refused from the *lengths*, before either string is copied. The + // store rejects an oversized entry anyway, but by then the host + // has already allocated and copied up to 64 KiB twice — a cost + // charged as one fixed-price wasm call, so a loop turns a fuel + // budget into allocation traffic the sandbox never sees. + let too_big = |len: i32| !(0..=(crate::kv::MAX_ENTRY as i32)).contains(&len); + if too_big(key_len) || too_big(val_len) { + return abi::outcome::REFUSED; + } + // And the same question about the call as a whole. One entry is + // bounded; the number of them was not, so a loop rewriting one + // key kept nothing and still moved as much memory as it liked — + // the store's budget bounds what is *kept*, and this bounds what + // is copied to keep it. + let spent = &mut c.data_mut().kv_bytes; + let asked = key_len as usize + val_len as usize; + if asked > MAX_KV_BYTES_PER_CALL.saturating_sub(*spent) { + return abi::outcome::REFUSED; + } + *spent += asked; + let [key, value] = match read_strs(&mut c, [(key, key_len), (val, val_len)]) { + Ok(read) => read, + Err(code) => return code, + }; + let kv = &mut c.data_mut().kv; + if durable { + kv.set_durable(&key, &value) + } else if kv.set(&key, &value) { + abi::outcome::ACCEPTED + } else { + abi::outcome::REFUSED + } + }, + )?; + } linker.func_wrap( m, @@ -1134,6 +1147,7 @@ fn link_free(linker: &mut Linker) -> Result<(), wasmi::Error> { fn root(node: &abi::ui::Node) -> Option { let slot = match node.slot { abi::ui::slot::CHAT_HEADER => PluginSlot::ChatHeader, + abi::ui::slot::COMPOSER => PluginSlot::Composer, abi::ui::slot::SETTINGS => PluginSlot::Settings, _ => return None, }; diff --git a/crates/plugin-host/src/kv.rs b/crates/plugin-host/src/kv.rs index 322f56fc..aa081f1d 100644 --- a/crates/plugin-host/src/kv.rs +++ b/crates/plugin-host/src/kv.rs @@ -14,7 +14,8 @@ use std::collections::BTreeMap; use std::sync::Arc; -use crate::store::Backing; +use crate::store::{Backing, ReplaceError}; +use oxidezap_plugin_abi::outcome; /// How much one plugin may keep. /// @@ -179,6 +180,38 @@ impl Kv { true } + /// Replace one entry and acknowledge only after the backing store writes it. + pub fn set_durable(&mut self, key: &str, value: &str) -> i32 { + if !self.store.keeps_answers() + || self + .wrote_at + .is_some_and(|at| at.elapsed() < MIN_WRITE_INTERVAL) + { + return outcome::REFUSED; + } + let previous = self.entries.get(key).cloned(); + let dirty = self.dirty; + let bytes = self.bytes; + if !self.set(key, value) { + return outcome::REFUSED; + } + match self.write_out() { + Ok(()) => return outcome::ACCEPTED, + Err(ReplaceError::Unconfirmed(_)) => return outcome::UNCONFIRMED, + Err(ReplaceError::Unchanged(_)) => {} + } + + // A failed write must not turn into a delayed commit of a rejected change. + if let Some(previous) = previous { + self.entries.insert(key.to_owned(), previous); + } else { + self.entries.remove(key); + } + self.dirty = dirty; + self.bytes = bytes; + outcome::REFUSED + } + /// Write out whatever the call changed, if it changed anything. /// /// Called once when a wasm call returns, which is what bounds the I/O a @@ -194,7 +227,7 @@ impl Kv { { return; } - self.write_out(); + let _ = self.write_out(); } /// When the pending change may be written, if there is one. @@ -220,18 +253,17 @@ impl Kv { /// For the one place where there is no next commit: a plugin that is /// stopping. Everything else goes through [`commit`](Self::commit). pub fn flush_pending(&mut self) { - self.write_out(); + let _ = self.write_out(); } - fn write_out(&mut self) { - if self.dirty { - // Cleared only by a write that landed. Taking the flag first - // meant a full disk lost the change silently: the map held it, - // nothing was dirty any more, and the next restart read back the - // older file. - self.dirty = !self.flush(); - self.wrote_at = Some(wacore::time::Instant::now()); + fn write_out(&mut self) -> Result<(), ReplaceError> { + if !self.dirty { + return Ok(()); } + let result = self.flush(); + self.dirty = result.is_err(); + self.wrote_at = Some(wacore::time::Instant::now()); + result } /// What the entries weigh, computed once when the store is opened. @@ -249,27 +281,22 @@ impl Kv { /// Answers whether what is held is now stored. `true` for a memory-only /// store: there is nothing it could fail to write, so nothing stays /// pending. - fn flush(&mut self) -> bool { - let Ok(json) = serde_json::to_vec(&self.entries) else { - return false; - }; - match self.store.write(&self.name, &json) { - Ok(()) => { - self.complained = false; - true - } - Err(e) => { - if !self.complained { - self.complained = true; - log::warn!( - "cannot write {}: {e}. This plugin's settings will not survive a \ - restart.", - self.store.describe(&self.name) - ); - } - false + fn flush(&mut self) -> Result<(), ReplaceError> { + let json = serde_json::to_vec(&self.entries) + .map_err(|error| ReplaceError::Unchanged(error.to_string()))?; + let result = self.store.replace(&self.name, &json); + if let Err(error) = &result { + if !self.complained { + self.complained = true; + log::warn!( + "cannot confirm write to {}: {error:?}", + self.store.describe(&self.name) + ); } + } else { + self.complained = false; } + result } } @@ -393,6 +420,66 @@ mod tests { assert_eq!(Kv::open(files(&dir.0), "p").get("k"), Some("second")); } + #[test] + fn durable_writes_acknowledge_persistence_and_refusals_preserve_the_entry() { + let dir = TempDir::new("durable"); + let mut kv = Kv::open(files(&dir.0), "p"); + assert_eq!(kv.set_durable("k", "committed"), outcome::ACCEPTED); + assert_eq!(Kv::open(files(&dir.0), "p").get("k"), Some("committed")); + assert_eq!(kv.set_durable("k", "too soon"), outcome::REFUSED); + assert_eq!(kv.get("k"), Some("committed")); + + let blocked = dir.0.join("blocked"); + std::fs::write(&blocked, "").unwrap(); + let mut kv = Kv::open(files(&blocked), "p"); + assert!(kv.set("k", "buffered")); + assert_eq!(kv.set_durable("k", "write failed"), outcome::REFUSED); + assert_eq!(kv.get("k"), Some("buffered")); + assert!(kv.due_at().is_some()); + + let mut memory_only = Kv::open(Arc::new(crate::store::Nowhere), "p"); + assert_eq!( + memory_only.set_durable("k", "no backing store"), + outcome::REFUSED + ); + assert_eq!(memory_only.get("k"), None); + } + + #[test] + fn a_replacement_with_unconfirmed_persistence_remains_visible() { + struct Unsynced(Files); + + impl Backing for Unsynced { + fn read(&self, name: &str, max: usize) -> Option> { + self.0.read(name, max) + } + + fn write(&self, name: &str, bytes: &[u8]) -> Result<(), String> { + self.0.write(name, bytes) + } + + fn replace(&self, name: &str, bytes: &[u8]) -> Result<(), ReplaceError> { + self.write(name, bytes).map_err(ReplaceError::Unchanged)?; + Err(ReplaceError::Unconfirmed("directory sync failed".into())) + } + + fn remove(&self, name: &str) -> Result<(), String> { + self.0.remove(name) + } + + fn describe(&self, name: &str) -> String { + self.0.describe(name) + } + } + + let dir = TempDir::new("unconfirmed"); + let mut kv = Kv::open(Arc::new(Unsynced(Files::at(&dir.0))), "p"); + assert_eq!(kv.set_durable("k", "replacement"), outcome::UNCONFIRMED); + assert_eq!(kv.get("k"), Some("replacement")); + assert_eq!(Kv::open(files(&dir.0), "p").get("k"), kv.get("k")); + assert!(kv.due_at().is_some()); + } + #[test] fn an_empty_value_deletes() { let dir = TempDir::new("delete"); diff --git a/crates/plugin-host/src/lib.rs b/crates/plugin-host/src/lib.rs index 4c66aca7..ea56b179 100644 --- a/crates/plugin-host/src/lib.rs +++ b/crates/plugin-host/src/lib.rs @@ -55,7 +55,7 @@ pub use registry::Sink; pub use store::Files; #[cfg(target_family = "wasm")] pub use store::Origin; -pub use store::{Backing, Nowhere}; +pub use store::{Backing, Nowhere, ReplaceError}; // What the store beside it asks of the filesystem: whether a file is one // another local account could have written, and how a write and a rename @@ -954,7 +954,7 @@ impl Live { // produce, so both are somebody else's client rather than a person // pressing something. let chat = match (action.slot, action.chat_jid.as_deref()) { - (PluginSlot::ChatHeader, Some(jid)) if !jid.is_empty() => jid, + (PluginSlot::ChatHeader | PluginSlot::Composer, Some(jid)) if !jid.is_empty() => jid, (PluginSlot::Settings, None) => "", (slot, _) => { log::debug!( diff --git a/crates/plugin-host/src/store/mod.rs b/crates/plugin-host/src/store/mod.rs index 781452b3..a788f3bc 100644 --- a/crates/plugin-host/src/store/mod.rs +++ b/crates/plugin-host/src/store/mod.rs @@ -13,6 +13,20 @@ //! What each implementation owes is narrower — hand back what was written, or //! nothing. +#[derive(Debug)] +pub enum ReplaceError { + Unchanged(String), + Unconfirmed(String), +} + +impl ReplaceError { + pub fn reason(self) -> String { + match self { + Self::Unchanged(reason) | Self::Unconfirmed(reason) => reason, + } + } +} + /// A named document that outlives the process. /// /// `Send + Sync` because the approvals are read from every thread the daemon @@ -39,6 +53,14 @@ pub trait Backing: Send + Sync + 'static { /// writes about it. fn write(&self, name: &str, bytes: &[u8]) -> Result<(), String>; + /// Like `write`, preserving whether failure happened before replacement + /// or while confirming a replacement already visible to readers. + /// + /// Backends that can fail after replacement must override this method. + fn replace(&self, name: &str, bytes: &[u8]) -> Result<(), ReplaceError> { + self.write(name, bytes).map_err(ReplaceError::Unchanged) + } + /// Remove `name`, durably. Missing is success. /// /// # Errors diff --git a/crates/plugin-host/src/store/native.rs b/crates/plugin-host/src/store/native.rs index 465877c8..e46fe3fe 100644 --- a/crates/plugin-host/src/store/native.rs +++ b/crates/plugin-host/src/store/native.rs @@ -8,7 +8,7 @@ use std::path::{Path, PathBuf}; -use super::Backing; +use super::{Backing, ReplaceError}; /// Files in one directory. Native only; a page has no directory to name. pub struct Files(PathBuf); @@ -61,6 +61,10 @@ impl Backing for Files { } fn write(&self, name: &str, bytes: &[u8]) -> Result<(), String> { + self.replace(name, bytes).map_err(ReplaceError::reason) + } + + fn replace(&self, name: &str, bytes: &[u8]) -> Result<(), ReplaceError> { let path = self.path(name); // Unique per process and thread. A fixed name is one two daemons // sharing a state directory both write, so one can rename a file the @@ -70,22 +74,16 @@ impl Backing for Files { std::process::id(), std::thread::current().id() )); - let landed = crate::write_private(&temp, bytes) - .and_then(|()| std::fs::rename(&temp, &path)) - // The rename is metadata, and syncing the file did not persist - // it: an answer that reported success while the entry was still - // only in memory is a withdrawal the next start hands back. - .and_then(|()| match path.parent() { - Some(dir) => crate::sync_dir(dir), - None => Ok(()), - }); - match landed { - Ok(()) => Ok(()), - Err(e) => { - let _ = std::fs::remove_file(&temp); - Err(e.to_string()) - } + if let Err(error) = + crate::write_private(&temp, bytes).and_then(|()| std::fs::rename(&temp, &path)) + { + let _ = std::fs::remove_file(&temp); + return Err(ReplaceError::Unchanged(error.to_string())); + } + if let Some(dir) = path.parent() { + crate::sync_dir(dir).map_err(|error| ReplaceError::Unconfirmed(error.to_string()))?; } + Ok(()) } fn remove(&self, name: &str) -> Result<(), String> { diff --git a/crates/plugin-host/src/tests.rs b/crates/plugin-host/src/tests.rs index dffea915..f31d729f 100644 --- a/crates/plugin-host/src/tests.rs +++ b/crates/plugin-host/src/tests.rs @@ -1133,6 +1133,77 @@ fn shutting_down_joins_every_plugin() { plugins.shutdown(); } +#[test] +#[ignore = "needs examples/schedule built for wasm32-unknown-unknown"] +fn the_schedule_plugin_submits_chat_forms_and_cancels_pending_messages() { + let built = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../examples/schedule/target/wasm32-unknown-unknown/release/schedule.wasm" + ); + let dir = TempDir::new("schedule-example"); + std::fs::copy(built, dir.0.join("schedule.wasm")).expect("build the schedule example first"); + let state = TempDir::new("schedule-example-state"); + let commands = Recorder::new(Outcome::Accepted); + let published = Published::default(); + let plugins = Plugins::load( + &dir.0, + Some(&state.0), + Arc::new(Arc::clone(&commands)), + published.sink(), + ); + published.settles("the composer form", |surfaces| { + surfaces.first().is_some_and(|surface| { + surface.is_running() && surface.roots_in(PluginSlot::Composer).next().is_some() + }) + }); + let chat = "15550100000@s.whatsapp.net"; + plugins.act(&PluginAction { + plugin: "schedule".into(), + action: "schedule".into(), + value: Some(r#"{"message":"see you later","when":"60"}"#.into()), + chat_jid: Some(chat.into()), + slot: PluginSlot::Composer, + widget: PluginWidget::Button, + }); + published.settles("the scheduled job", |surfaces| { + surfaces[0] + .roots_in(PluginSlot::Settings) + .any(|root| root.children.iter().any(|child| child.id == "cancel-1")) + }); + std::thread::sleep(Duration::from_millis(1100)); + plugins.act(&PluginAction { + plugin: "schedule".into(), + action: "cancel-1".into(), + value: None, + chat_jid: None, + slot: PluginSlot::Settings, + widget: PluginWidget::Button, + }); + published.settles("the cancelled job", |surfaces| { + surfaces[0] + .roots_in(PluginSlot::Settings) + .all(|root| root.children.iter().all(|child| child.id != "cancel-1")) + }); + assert!(commands.sent().is_empty()); + + std::thread::sleep(Duration::from_millis(1100)); + assert!(plugins.approve("schedule", true)); + let due = wacore::time::now_utc() + Duration::from_secs(3); + plugins.act(&PluginAction { + plugin: "schedule".into(), + action: "schedule".into(), + value: Some(format!( + r#"{{"message":"due now","when":"{}"}}"#, + due.to_rfc3339() + )), + chat_jid: Some(chat.into()), + slot: PluginSlot::Composer, + widget: PluginWidget::Button, + }); + published.settles("the timer sends the job", |_| !commands.sent().is_empty()); + assert_eq!(commands.sent(), [(chat.into(), "due now".into(), None)]); +} + /// The real SDK, against the real host. /// /// Ignored by default because it needs the example built for wasm32, which diff --git a/crates/plugin-sdk/src/lib.rs b/crates/plugin-sdk/src/lib.rs index b60c0d31..24de042b 100644 --- a/crates/plugin-sdk/src/lib.rs +++ b/crates/plugin-sdk/src/lib.rs @@ -275,6 +275,8 @@ pub enum Outcome { /// [`Invalid`]: Self::Invalid /// [`Denied`]: Self::Denied State, + /// The entry changed, but its persistence could not be confirmed. + Unconfirmed, } impl Outcome { @@ -285,6 +287,7 @@ impl Outcome { abi::outcome::DENIED => Self::Denied, abi::outcome::REFUSED => Self::Refused, abi::outcome::STATE => Self::State, + abi::outcome::UNCONFIRMED => Self::Unconfirmed, _ => Self::Invalid, } } @@ -824,7 +827,7 @@ impl Action<'_> { } /// What it now holds — a toggle's new state as `1` or `0`, a field's - /// contents, and nothing at all for a button. + /// contents, or a JSON object of field values for a composer button. #[must_use] pub fn value(self) -> Text<256> { self.0.text(fields::ACTION_VALUE) @@ -1207,6 +1210,20 @@ pub fn set(key: &str, value: &str) -> Outcome { }) } +/// Store a value and wait for the backing store to accept the write. +/// +/// Shares the normal storage write limit. A refused change is not queued. An unconfirmed change is visible in memory. +pub fn set_durable(key: &str, value: &str) -> Outcome { + Outcome::of(unsafe { + raw::kv_set_durable( + raw::at(key.as_bytes()), + key.len() as i32, + raw::at(value.as_bytes()), + value.len() as i32, + ) + }) +} + /// A plugin's own small store, in the shapes a plugin actually keeps. /// /// Values are strings on the wire, because that is what the ABI carries. The diff --git a/crates/plugin-sdk/src/raw.rs b/crates/plugin-sdk/src/raw.rs index 6218dd87..af952760 100644 --- a/crates/plugin-sdk/src/raw.rs +++ b/crates/plugin-sdk/src/raw.rs @@ -82,6 +82,8 @@ unsafe extern "C" { pub fn kv_get(key: Ptr, key_len: i32, ptr: Ptr, cap: i32) -> i32; #[link_name = "oxi_kv_set"] pub fn kv_set(key: Ptr, key_len: i32, val: Ptr, val_len: i32) -> i32; + #[link_name = "oxi_kv_set_durable"] + pub fn kv_set_durable(key: Ptr, key_len: i32, val: Ptr, val_len: i32) -> i32; #[link_name = "oxi_timer_set"] pub safe fn timer_set(delay_ms: i64, token: i64) -> i32; @@ -199,6 +201,16 @@ mod off_target { borrow(val, val_len) }) } + pub unsafe fn kv_set_durable( + key: super::Ptr, + key_len: i32, + val: super::Ptr, + val_len: i32, + ) -> i32 { + testing::kv_set_durable(unsafe { borrow(key, key_len) }, unsafe { + borrow(val, val_len) + }) + } pub fn timer_set(delay_ms: i64, token: i64) -> i32 { testing::command(testing::Command::Timer { delay_ms, token }) } @@ -271,6 +283,14 @@ mod off_target { pub unsafe fn kv_set(_key: super::Ptr, _key_len: i32, _val: super::Ptr, _val_len: i32) -> i32 { nowhere() } + pub unsafe fn kv_set_durable( + _key: super::Ptr, + _key_len: i32, + _val: super::Ptr, + _val_len: i32, + ) -> i32 { + nowhere() + } pub fn timer_set(_delay_ms: i64, _token: i64) -> i32 { nowhere() } diff --git a/crates/plugin-sdk/src/testing.rs b/crates/plugin-sdk/src/testing.rs index cca8c9c1..72609d30 100644 --- a/crates/plugin-sdk/src/testing.rs +++ b/crates/plugin-sdk/src/testing.rs @@ -138,6 +138,7 @@ struct State { subscription: i64, capabilities: i64, now_ms: i64, + unconfirmed_write: bool, } thread_local! { @@ -253,6 +254,11 @@ impl Host { } /// What `oxi_now_ms` answers. Zero unless a test says otherwise, so a + /// Replace the value on the next durable write and report uncertainty. + pub fn unconfirm_next_durable_write(&mut self) { + HOST.with(|host| host.borrow_mut().unconfirmed_write = true); + } + /// plugin that stamps something is testable at all. pub fn set_now_ms(&mut self, now: i64) { HOST.with(|h| h.borrow_mut().now_ms = now); @@ -370,6 +376,15 @@ pub(crate) fn kv_set(key: &str, value: &str) -> i32 { abi::outcome::ACCEPTED } +pub(crate) fn kv_set_durable(key: &str, value: &str) -> i32 { + let outcome = kv_set(key, value); + if HOST.with(|host| core::mem::take(&mut host.borrow_mut().unconfirmed_write)) { + abi::outcome::UNCONFIRMED + } else { + outcome + } +} + #[cfg(test)] mod tests { use super::*; diff --git a/docs/plugin-abi.md b/docs/plugin-abi.md index a60eadfa..6732fa78 100644 --- a/docs/plugin-abi.md +++ b/docs/plugin-abi.md @@ -91,6 +91,7 @@ returns an outcome (below). | `oxi_ui_set` | `(ptr, len) -> i32` | `UI` | | `oxi_kv_get` | `(key, key_len, ptr, cap) -> i32` | `STORAGE` | | `oxi_kv_set` | `(key, key_len, val, val_len) -> i32` | `STORAGE` | +| `oxi_kv_set_durable` | `(key, key_len, val, val_len) -> i32` | `STORAGE` | | `oxi_timer_set` | `(delay_ms: i64, token: i64) -> i32` | `TIMERS` | | `oxi_log` | `(level: i32, ptr: i32, len: i32)` | none | | `oxi_now_ms` | `() -> i64` | none | @@ -102,6 +103,15 @@ action then writes over the user's own. An empty value passed to `oxi_kv_set` deletes the key. `oxi_ui_set` replaces the plugin's whole published tree. +`oxi_kv_set_durable` applies the same limits as `oxi_kv_set`. It returns +`ACCEPTED` only after the backing store acknowledges the write. It refuses +writes without persistent storage, during the normal one-second storage +write interval, or when the backing write fails before replacing the entry. +A refused change is not queued. If replacement succeeded but the backing +store could not confirm persistence, it returns `UNCONFIRMED` and keeps +the new value visible. Use it before an external action that must not be replayed on restart. +Modules importing it need a host that provides this import. + `oxi_now_ms` is the only clock: Unix milliseconds, which is the resolution a plugin needs to stamp a message or space its own timers. Read it as the resolution and not as a mitigation. The host neither quantises nor jitters it, @@ -117,6 +127,7 @@ call's fuel, so nothing here is a promise about timing side channels. | `-2` | `REFUSED` | The daemon will not do this as asked. | | `-3` | `DENIED` | The plugin did not declare this capability, or the user has not agreed to it. | | `-4` | `INVALID` | A pointer outside memory, bytes that are not UTF-8, a length past what the host accepts. | +| `-6` | `UNCONFIRMED` | The store replaced the value but could not confirm persistence. | | `-5` | `STATE` | Right call, wrong moment — declaring outside `oxi_init`, or acting inside it. | `-1` is also `ABSENT` for the field reads, where there is no outcome to @@ -253,10 +264,9 @@ node: Kinds: `1` button, `2` toggle, `3` label, `4` text field, `5` row, `6` column, `7` section. Only rows, columns and sections are drawn with children. -Slots: `1` chat header, `3` settings. `2` is **reserved and undefined** — the -composer's number, unassigned on purpose, because a slot the front end -silently ignores is a button whose author never finds out why it did not -appear. +Slots: `1` chat header, `2` composer tools popover, `3` settings. Actions +in the header and composer slots carry the open chat. Use the composer slot +for forms and tools that act on that conversation. Flags: `1` enabled, `2` checked. @@ -299,12 +309,17 @@ so they are decoded strictly — a broken byte in an id is an error, where a broken byte in a label is replaced and drawn. When somebody uses a widget, `UI_ACTION` arrives carrying `ACTION_ID`, -`ACTION_VALUE` (a toggle's *new* state as `1`/`0`, a field's contents, empty -for a button) and `CHAT_JID` for a slot that has a chat behind it. The daemon +`ACTION_VALUE` (a toggle's *new* state as `1`/`0`, a field's contents, or +a composer button's form values) and `CHAT_JID` for a slot that has a chat +behind it. The daemon checks the action against the tree it currently publishes — kind and slot included — so a press from a window whose frame is older than the daemon's does not land as a real one. +Composer text fields are local until a composer button is pressed. That button +receives a JSON object mapping the plugin's composer field IDs to the values +currently visible in the same chat. Other buttons have an empty value. + ## What the host holds a plugin to Fuel meters the instructions a plugin runs, not the work the host does when diff --git a/examples/schedule/Cargo.lock b/examples/schedule/Cargo.lock new file mode 100644 index 00000000..9972705c --- /dev/null +++ b/examples/schedule/Cargo.lock @@ -0,0 +1,144 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "num-traits", +] + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "oxidezap-plugin" +version = "0.1.0" +dependencies = [ + "oxidezap-plugin-abi", +] + +[[package]] +name = "oxidezap-plugin-abi" +version = "0.1.0" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "schedule" +version = "0.1.0" +dependencies = [ + "chrono", + "oxidezap-plugin", + "serde", + "serde_json", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/examples/schedule/Cargo.toml b/examples/schedule/Cargo.toml new file mode 100644 index 00000000..99781d77 --- /dev/null +++ b/examples/schedule/Cargo.toml @@ -0,0 +1,29 @@ +[package] +name = "schedule" +description = "Schedule text messages from the OxideZap composer" +version = "0.1.0" +edition = "2024" +rust-version = "1.100.0" +license = "MIT" +publish = false + +[workspace] + +[lib] +crate-type = ["cdylib"] + +[dependencies] +oxidezap-plugin = { path = "../../crates/plugin-sdk" } +chrono = { version = "0.4", default-features = false, features = ["alloc"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[dev-dependencies] +oxidezap-plugin = { path = "../../crates/plugin-sdk", features = ["testing"] } + +[profile.release] +opt-level = "z" +lto = "fat" +codegen-units = 1 +panic = "abort" +strip = true diff --git a/examples/schedule/README.md b/examples/schedule/README.md new file mode 100644 index 00000000..28a504ba --- /dev/null +++ b/examples/schedule/README.md @@ -0,0 +1,24 @@ +# Scheduled messages + +Build the plugin from the repository root: + +```sh +cargo xtask plugin build examples/schedule +``` + +Install the resulting `schedule.wasm` in Settings → Plugins and approve +sending messages. In a direct chat or group, open **Chat tools** by the +composer. Enter the message and either minutes from now or an RFC 3339 +time with an explicit offset, such as `2026-11-21T14:30:00-03:00`. +Press **Schedule**. The plugin's Settings panel lists pending messages and +lets you cancel them. + +The queue is stored per account. Keep the daemon running on desktop or +the app's host tab open on web for on-time attempts. The plugin checks due +messages when it starts and every five seconds thereafter. A disconnected +account keeps its jobs until it reconnects. + +The plugin records an attempt before handing the message to the account. +An accepted command is handed off once. Acceptance is not a WhatsApp +delivery receipt. A crash in the handoff leaves an unconfirmed entry in +Settings for manual inspection. The plugin does not replay it automatically. diff --git a/examples/schedule/src/lib.rs b/examples/schedule/src/lib.rs new file mode 100644 index 00000000..5dbf4bf5 --- /dev/null +++ b/examples/schedule/src/lib.rs @@ -0,0 +1,381 @@ +use chrono::{DateTime, Utc}; +use oxidezap_plugin::{ + Action, Caps, Declared, Event, Kinds, Outcome, Setup, Which, now_ms, plugin, ui, +}; +use serde::{Deserialize, Serialize}; + +plugin!(init = setup, event = handle, panic = own); + +const STORE: &str = "messages"; +const TICK: i64 = 1; +const MAX_QUEUE_BYTES: usize = 8192; +const MAX_JOBS: usize = 8; +const MAX_MESSAGE: usize = 512; +const POLL_MS: i64 = 5_000; + +#[derive(Clone, Serialize, Deserialize)] +struct Job { + id: u64, + jid: String, + text: String, + at: i64, + attempting: bool, +} + +#[derive(Clone, Default, Serialize, Deserialize)] +struct Queue { + last_id: u64, + jobs: Vec, +} + +#[derive(Deserialize)] +struct Form { + message: String, + when: String, +} + +fn setup(p: Setup) -> impl Declared { + let declared = p + .name("Scheduled messages") + .subscribe(Kinds::NONE) + .capabilities(Caps::UI | Caps::STORAGE | Caps::TIMERS | Caps::SEND); + draw(&read_queue(), ""); + oxidezap_plugin::after(100, TICK); + declared +} + +fn read_queue() -> Result { + let stored = oxidezap_plugin::get::(STORE); + let Some(raw) = stored.whole().filter(|_| !stored.refused()) else { + return if stored.refused() || stored.present() { + Err("The schedule could not be read.") + } else { + Ok(Queue::default()) + }; + }; + if !stored.present() { + return Ok(Queue::default()); + } + serde_json::from_str(raw).map_err(|_| "The stored schedule could not be read.") +} + +fn save(queue: &Queue, durable: bool) -> Result<(), &'static str> { + let raw = serde_json::to_string(queue).map_err(|_| "The schedule could not be saved.")?; + if raw.len() > MAX_QUEUE_BYTES { + return Err("The schedule is past its storage limit."); + } + let outcome = if durable { + oxidezap_plugin::set_durable(STORE, &raw) + } else { + oxidezap_plugin::set(STORE, &raw) + }; + match outcome { + Outcome::Accepted => Ok(()), + Outcome::Unconfirmed => Err( + "The schedule changed, but storage could not confirm the write. Check the list before retrying.", + ), + _ => Err("The schedule could not be saved. Try again in a moment."), + } +} + +fn chat_supported(jid: &str) -> bool { + jid.rsplit_once('@').is_some_and(|(user, server)| { + !user.is_empty() + && user.bytes().all(|b| b.is_ascii_digit() || b == b'-') + && matches!(server, "s.whatsapp.net" | "lid" | "g.us") + }) +} + +fn deadline(when: &str, now: i64) -> Option { + let when = when.trim(); + let at = if let Ok(minutes) = when.parse::() { + now.checked_add(minutes.checked_mul(60_000)?)? + } else { + DateTime::parse_from_rfc3339(when).ok()?.timestamp_millis() + }; + (at > now && at.saturating_sub(now) <= 366 * 86_400_000).then_some(at) +} + +fn edit_queue(action: Action<'_>, queue: &mut Queue) -> Result<&'static str, &'static str> { + let id = action.id(); + let chat = action.chat(); + let jid = chat.as_str(); + if let Some(id) = id + .as_str() + .strip_prefix("cancel-") + .and_then(|id| id.parse::().ok()) + { + queue.jobs.retain(|job| job.id != id); + save(queue, true)?; + return Ok("Removed from the schedule."); + } + if !chat_supported(jid) { + return Err("Open a direct conversation or group to schedule a message."); + } + if id.as_str() != "schedule" { + return Ok(""); + } + if queue.jobs.len() >= MAX_JOBS { + return Err("The schedule is full."); + } + let value = action.value_into::<4096>(); + let form: Form = value + .whole() + .and_then(|raw| serde_json::from_str(raw).ok()) + .ok_or("The form could not be read.")?; + if form.message.trim().is_empty() || form.message.len() > MAX_MESSAGE { + return Err("Enter a message of up to 512 bytes."); + } + let now = now_ms(); + let at = deadline(&form.when, now).ok_or("Enter a future time within one year.")?; + if queue + .jobs + .iter() + .any(|job| job.jid == jid && job.text == form.message && job.at.abs_diff(at) < 5_000) + { + return Err("This message is already in the schedule."); + } + queue.last_id = queue + .last_id + .checked_add(1) + .ok_or("The schedule is full.")?; + queue.jobs.push(Job { + id: queue.last_id, + jid: jid.into(), + text: form.message, + at, + attempting: false, + }); + save(queue, true)?; + Ok("Message scheduled. Manage it in the plugin settings.") +} + +fn tick(queue: &mut Queue) -> Result { + let now = now_ms(); + let Some(index) = queue + .jobs + .iter() + .enumerate() + .filter(|(_, job)| !job.attempting && job.at <= now) + .min_by_key(|(_, job)| (job.at, job.id)) + .map(|(index, _)| index) + else { + return Ok(false); + }; + // A restart between this write and the send cannot replay an uncertain send. + queue.jobs[index].attempting = true; + if let Err(error) = save(queue, true) { + // No send was attempted. Undo a marker that may have replaced the + // file so a later timer can try again. + queue.jobs[index].attempting = false; + save(queue, false)?; + return Err(error); + } + let job = &queue.jobs[index]; + match oxidezap_plugin::send_text(&job.jid, &job.text) { + Outcome::Accepted => { + queue.jobs.remove(index); + } + Outcome::NoSession | Outcome::Denied | Outcome::Refused => { + queue.jobs[index].attempting = false; + } + Outcome::Invalid | Outcome::State | Outcome::Unconfirmed => return Ok(true), + } + save(queue, false)?; + Ok(true) +} + +fn handle(event: &Event) { + match event.which() { + Which::Action(action) => { + let queue = read_queue(); + let mut proposed = queue.clone(); + match proposed.as_mut().map(|queue| edit_queue(action, queue)) { + Ok(Ok(status)) => draw(&proposed, status), + Ok(Err(error)) => draw(&read_queue(), error), + Err(error) => draw(&queue, error), + } + } + Which::Timer(timer) if timer.token() == TICK => { + let mut queue = read_queue(); + match queue.as_mut().map(tick) { + Ok(Ok(true)) => draw(&queue, ""), + Ok(Err(error)) => draw(&read_queue(), error), + _ => {} + } + oxidezap_plugin::after(POLL_MS, TICK); + } + _ => {} + } +} + +fn draw(queue: &Result, notice: &str) { + ui::publish::<16384>(|ui| { + ui.section(ui::slot::COMPOSER, "Schedule a message", |section| { + section.field("message", "Message (up to 512 bytes)", "", true); + section.field( + "when", + "Minutes from now or RFC 3339 date with offset", + "", + true, + ); + section.button("schedule", "Schedule"); + if !notice.is_empty() { + section.label(notice); + } + }); + ui.section(ui::slot::SETTINGS, "Scheduled messages", |section| { + if !notice.is_empty() { + section.label(notice); + } + let queue = match queue { + Ok(queue) => queue, + Err(error) => { + section.label(error); + return; + } + }; + if queue.jobs.is_empty() { + section.label("No scheduled messages."); + } + for job in &queue.jobs { + let when = DateTime::::from_timestamp_millis(job.at) + .map(|time| time.to_rfc3339()) + .unwrap_or_default(); + section.label(&format!("{} · {}", job.jid, when)); + section.label(&job.text); + let label = if job.attempting { + "Dismiss unconfirmed send" + } else { + "Cancel scheduled message" + }; + section.button(&format!("cancel-{}", job.id), label); + } + }); + }); +} + +#[cfg(test)] +mod tests { + use super::*; + use oxidezap_plugin::{ + abi, + testing::{Event as In, Host}, + }; + + const CHAT: &str = "15550100000@s.whatsapp.net"; + + fn schedule(host: &mut Host, chat: &str, when: &str) { + let value = serde_json::json!({"message": "hello", "when": when}).to_string(); + host.deliver( + In::action("schedule", &value).str(abi::fields::CHAT_JID, chat), + handle, + ); + } + + #[test] + fn persisted_job_is_sent_once_at_or_after_its_deadline() { + let mut host = Host::new(); + host.init(setup); + assert!( + host.ui() + .unwrap() + .unwrap() + .iter() + .any(|node| node.slot == ui::slot::COMPOSER) + ); + host.set_now_ms(1_000); + schedule(&mut host, CHAT, "1"); + host.deliver(In::timer(TICK), handle); + assert!(host.sent().is_empty()); + + let saved = host.stored(STORE).unwrap(); + let mut restarted = Host::new(); + restarted.store(STORE, &saved); + restarted.init(setup); + restarted.set_now_ms(61_000); + restarted.deliver(In::timer(TICK), handle); + restarted.deliver(In::timer(TICK), handle); + assert_eq!(restarted.sent(), [(CHAT.to_owned(), "hello".to_owned())]); + } + + #[test] + fn invalid_destinations_and_cancelled_jobs_do_not_send() { + let mut host = Host::new(); + host.init(setup); + schedule(&mut host, "status@broadcast", "1"); + assert!(host.stored(STORE).is_none()); + schedule(&mut host, CHAT, "1"); + host.deliver(In::action("cancel-1", ""), handle); + host.set_now_ms(60_000); + host.deliver(In::timer(TICK), handle); + assert!(host.sent().is_empty()); + } + + #[test] + fn an_unconfirmed_marker_is_retried_without_sending_early() { + let mut host = Host::new(); + host.init(setup); + schedule(&mut host, CHAT, "1"); + host.set_now_ms(60_000); + host.unconfirm_next_durable_write(); + host.deliver(In::timer(TICK), handle); + assert!(host.sent().is_empty()); + let stored: Queue = serde_json::from_str(&host.stored(STORE).unwrap()).unwrap(); + assert!(!stored.jobs[0].attempting); + host.deliver(In::timer(TICK), handle); + assert_eq!(host.sent().len(), 1); + } + + #[test] + fn a_restart_does_not_replay_an_unconfirmed_attempt() { + let mut host = Host::new(); + let queue = Queue { + last_id: 1, + jobs: vec![Job { + id: 1, + jid: CHAT.into(), + text: "hello".into(), + at: 100, + attempting: true, + }], + }; + host.store(STORE, &serde_json::to_string(&queue).unwrap()); + host.init(setup); + host.set_now_ms(100); + host.deliver(In::timer(TICK), handle); + assert!(host.sent().is_empty()); + } + + #[test] + fn an_oversized_serialized_queue_does_not_publish_an_unsaved_job() { + let mut host = Host::new(); + host.init(setup); + let value = serde_json::json!({"message": "\0".repeat(512), "when": "1"}).to_string(); + for n in 0..3 { + host.set_now_ms(n * 60_000); + host.deliver( + In::action("schedule", &value).str(abi::fields::CHAT_JID, CHAT), + handle, + ); + } + let saved: Queue = serde_json::from_str(&host.stored(STORE).unwrap()).unwrap(); + assert_eq!(saved.jobs.len(), 2); + let tree = host.ui().unwrap().unwrap(); + assert_eq!( + tree.iter() + .flat_map(|node| &node.children) + .filter(|node| node.id.starts_with("cancel-")) + .count(), + 2 + ); + } + + #[test] + fn parses_offsets_without_assuming_the_daemon_timezone() { + assert_eq!(deadline("1970-01-01T00:01:00Z", 0), Some(60_000)); + assert_eq!(deadline("1970-01-01T01:01:00+01:00", 0), Some(60_000)); + assert_eq!(deadline("1970-01-01T00:01:00", 0), None); + assert_eq!(deadline("-1", 0), None); + } +}