nautilus_plugin/
lib.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Plug-in API and ABI surface for [NautilusTrader](https://nautilustrader.io).
17//!
18//! This crate defines the C-ABI boundary between a Nautilus host (the live node) and
19//! independently compiled Rust plug-in cdylibs. Plug-ins ship a single
20//! `nautilus_plugin_init` symbol and a `'static` [`PluginManifest`]; the host
21//! `dlopen`s the library, calls the entry point, and registers every plug point
22//! the manifest enumerates.
23//!
24//! # Layout
25//!
26//! Infrastructure modules describe how plug-ins work at the boundary:
27//!
28//! - [`boundary`]: primitive `#[repr(C)]` types used at the boundary
29//!   ([`BorrowedStr`], [`Slice`], [`PluginError`], etc.).
30//! - [`manifest`]: the static manifest a plug-in returns and the per-plug-point
31//!   registration entries it contains.
32//! - [`host`]: the `HostVTable` of function pointers the host gives to the
33//!   plug-in for re-entrant callbacks (msgbus, clock, logging, etc.).
34//! - [`mod@panic`]: a `catch_unwind` wrapper that every macro-generated thunk
35//!   uses to stop a plug-in panic from unwinding across the FFI boundary.
36//!
37//! Per-plug-point trait surfaces live under [`surfaces`]:
38//!
39//! - [`surfaces::custom_data`]: custom data type plug-point.
40//! - [`surfaces::actor`]: plug-in actor (`DataActor`-shaped) plug-point.
41//! - [`surfaces::strategy`]: plug-in strategy (`Strategy`-shaped) plug-point.
42//! - [`surfaces::controller`]: controller plug-point with prepare hooks and
43//!   runtime strategy-control host services.
44//!
45//! Host-side loading lives behind the `host` feature and uses `libloading`.
46
47/// ABI version of the plug-in contract.
48///
49/// The host refuses to load a plug-in whose [`PluginManifest::abi_version`]
50/// does not match this value. The plug-in surface is unreleased and unstable,
51/// so this value remains `1` during alpha and does not promise compatibility
52/// between Nautilus versions. Rebuild plug-in cdylibs against the matching
53/// host version.
54///
55/// [`PluginManifest::abi_version`]: crate::manifest::PluginManifest::abi_version
56pub const NAUTILUS_PLUGIN_ABI_VERSION: u32 = 1;
57
58/// Schema version for [`manifest::PluginBuildId`].
59pub const PLUGIN_BUILD_ID_VERSION: u32 = 1;
60
61/// Name of the single `extern "C"` entry symbol every plug-in cdylib must export.
62///
63/// The host looks up this symbol via `libloading::Symbol` after `dlopen`.
64pub const NAUTILUS_PLUGIN_INIT_SYMBOL: &[u8] = b"nautilus_plugin_init";
65
66pub mod boundary;
67pub mod host;
68pub mod manifest;
69pub mod panic;
70pub mod surfaces;
71
72#[cfg(feature = "host")]
73pub mod bridge;
74
75#[cfg(feature = "host")]
76pub mod loader;
77
78mod macros;
79mod normalize;
80
81pub use boundary::{BorrowedStr, OwnedBytes, PluginError, PluginErrorCode, PluginResult, Slice};
82pub use host::{ControllerHostContext, ControllerHostVTable, HostContext, HostVTable};
83pub use manifest::{
84    ActorRegistration, ControllerRegistration, CustomDataRegistration, PluginBuildId, PluginInitFn,
85    PluginManifest, StrategyRegistration,
86};
87#[cfg(feature = "host")]
88pub use manifest::{
89    ValidatedActorRegistration, ValidatedActorVTable, ValidatedControllerRegistration,
90    ValidatedControllerVTable, ValidatedCustomDataRegistration, ValidatedCustomDataVTable,
91    ValidatedPluginManifest, ValidatedStrategyRegistration, ValidatedStrategyVTable,
92};
93pub use surfaces::{
94    actor::PluginActor,
95    controller::PluginController,
96    custom_data::{PluginCustomData, PluginCustomDataRef},
97    strategy::PluginStrategy,
98};
99
100/// Re-exports that plug-in authors typically want in scope.
101pub mod prelude {
102    pub use crate::{
103        BorrowedStr, ControllerHostContext, ControllerHostVTable, HostContext, HostVTable,
104        NAUTILUS_PLUGIN_ABI_VERSION, PluginActor, PluginBuildId, PluginController,
105        PluginCustomData, PluginCustomDataRef, PluginError, PluginErrorCode, PluginManifest,
106        PluginResult, PluginStrategy, Slice,
107    };
108}
nautilus_plugin/lib.rs

nautilus_plugin/
lib.rs
