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    AccumulatorDeclarationEntry, CloacinaMetadata, GraphExecutionRequest, GraphExecutionResult,
40    GraphPackageMetadata, PackageTasksMetadata, TaskExecutionRequest, TaskExecutionResult,
41    TaskMetadataEntry, TriggerDefinition,
42};
43
44// Re-export fidius crates so generated code can reference them
45pub use fidius;
46pub use fidius_core;
47
48// Re-export fidius modules needed by generated code when crate = "cloacina_workflow_plugin"
49pub use fidius_core::descriptor;
50pub use fidius_core::inventory;
51pub use fidius_core::registry;
52pub use fidius_core::status;
53pub use fidius_core::wire;
54
55// Re-export fidius types that plugin authors need
56pub use fidius::plugin_impl;
57pub use fidius_core::error::PluginError;
58pub use fidius_core::package::{PackageHeader, PackageManifest};
59
60// Re-export the plugin registry macro
61pub use fidius::fidius_plugin_registry;
62
63/// The plugin interface for cloacina workflow packages.
64///
65/// Every packaged workflow implements this trait (via `#[plugin_impl]` generated
66/// by the `#[workflow]` macro). The host calls these methods through a fidius
67/// `PluginHandle` — never directly.
68///
69/// ## Methods
70///
71/// - `get_task_metadata` — Returns metadata about all tasks in the workflow
72///   (IDs, dependencies, descriptions). Called once at registration time.
73///
74/// - `execute_task` — Runs a specific task by name with a JSON-serialized
75///   context. Returns the updated context or an error.
76#[fidius::plugin_interface(version = 1, buffer = PluginAllocated)]
77pub trait CloacinaPlugin: Send + Sync {
78    /// Returns metadata about all tasks in this workflow package.
79    /// Method index 0.
80    fn get_task_metadata(&self) -> Result<PackageTasksMetadata, PluginError>;
81
82    /// Executes a task by name with the given context.
83    /// Method index 1.
84    fn execute_task(
85        &self,
86        request: TaskExecutionRequest,
87    ) -> Result<TaskExecutionResult, PluginError>;
88
89    /// Returns metadata about the computation graph in this package.
90    /// Method index 2. Only called when package_type includes "computation_graph".
91    /// Workflow-only plugins should return an error.
92    fn get_graph_metadata(&self) -> Result<GraphPackageMetadata, PluginError>;
93
94    /// Executes the computation graph with the given cache state.
95    /// Method index 3. Only called when package_type includes "computation_graph".
96    /// Workflow-only plugins should return an error.
97    fn execute_graph(
98        &self,
99        request: GraphExecutionRequest,
100    ) -> Result<GraphExecutionResult, PluginError>;
101}
cloacina_workflow_plugin/lib.rs

cloacina_workflow_plugin/
lib.rs
