cloacina_workflow_plugin/
lib.rs

1/*
2 *  Copyright 2025-2026 Colliery Software
3 *
4 *  Licensed under the Apache License, Version 2.0 (the "License");
5 *  you may not use this file except in compliance with the License.
6 *  You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *  Unless required by applicable law or agreed to in writing, software
11 *  distributed under the License is distributed on an "AS IS" BASIS,
12 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 *  See the License for the specific language governing permissions and
14 *  limitations under the License.
15 */
16
17//! Cloacina plugin interface for the fidius plugin system.
18//!
19//! This crate defines the plugin contract between cloacina workflow packages
20//! (compiled as cdylib plugins) and the cloacina host engine. Both sides
21//! depend on this crate — it is the single source of truth for the FFI ABI.
22//!
23//! # For plugin authors
24//!
25//! Use `#[workflow]` with `features = ["packaged"]` — the macro generates
26//! the `#[plugin_impl(CloacinaPlugin)]` code automatically. You don't need
27//! to implement this trait directly.
28//!
29//! # For host integration
30//!
31//! Use `fidius-host` to load plugins and call methods through `PluginHandle`.
32//! Validate loaded plugins against `CloacinaPlugin_INTERFACE_HASH` to detect
33//! ABI drift at load time.
34
35pub mod types;
36
37// Re-export the interface types for convenience
38pub use types::{
39    CloacinaMetadata, PackageTasksMetadata, TaskExecutionRequest, TaskExecutionResult,
40    TaskMetadataEntry, TriggerDefinition,
41};
42
43// Re-export fidius crates so generated code can reference them
44pub use fidius;
45pub use fidius_core;
46
47// Re-export fidius modules needed by generated code when crate = "cloacina_workflow_plugin"
48pub use fidius_core::descriptor;
49pub use fidius_core::inventory;
50pub use fidius_core::registry;
51pub use fidius_core::status;
52pub use fidius_core::wire;
53
54// Re-export fidius types that plugin authors need
55pub use fidius::plugin_impl;
56pub use fidius_core::error::PluginError;
57pub use fidius_core::package::{PackageHeader, PackageManifest};
58
59// Re-export the plugin registry macro
60pub use fidius::fidius_plugin_registry;
61
62/// The plugin interface for cloacina workflow packages.
63///
64/// Every packaged workflow implements this trait (via `#[plugin_impl]` generated
65/// by the `#[workflow]` macro). The host calls these methods through a fidius
66/// `PluginHandle` — never directly.
67///
68/// ## Methods
69///
70/// - `get_task_metadata` — Returns metadata about all tasks in the workflow
71///   (IDs, dependencies, descriptions). Called once at registration time.
72///
73/// - `execute_task` — Runs a specific task by name with a JSON-serialized
74///   context. Returns the updated context or an error.
75#[fidius::plugin_interface(version = 1, buffer = PluginAllocated)]
76pub trait CloacinaPlugin: Send + Sync {
77    /// Returns metadata about all tasks in this workflow package.
78    fn get_task_metadata(&self) -> Result<PackageTasksMetadata, PluginError>;
79
80    /// Executes a task by name with the given context.
81    fn execute_task(
82        &self,
83        request: TaskExecutionRequest,
84    ) -> Result<TaskExecutionResult, PluginError>;
85}
cloacina_workflow_plugin/lib.rs

cloacina_workflow_plugin/
lib.rs
