nautilus-plugin 0.58.0

Plug-in system for the Nautilus trading engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Plug-in API and ABI surface for [NautilusTrader](https://nautilustrader.io).
//!
//! This crate defines the C-ABI boundary between a Nautilus host (the live node) and
//! independently compiled Rust plug-in cdylibs. Plug-ins ship a single
//! `nautilus_plugin_init` symbol and a `'static` [`PluginManifest`]; the host
//! `dlopen`s the library, calls the entry point, and registers every plug point
//! the manifest enumerates.
//!
//! # Layout
//!
//! Infrastructure modules describe how plug-ins work at the boundary:
//!
//! - [`boundary`]: primitive `#[repr(C)]` types used at the boundary
//!   ([`BorrowedStr`], [`Slice`], [`PluginError`], etc.).
//! - [`manifest`]: the static manifest a plug-in returns and the per-plug-point
//!   registration entries it contains.
//! - [`host`]: the `HostVTable` of function pointers the host gives to the
//!   plug-in for re-entrant callbacks (msgbus, clock, logging, etc.).
//! - [`mod@panic`]: a `catch_unwind` wrapper that every macro-generated thunk
//!   uses to stop a plug-in panic from unwinding across the FFI boundary.
//!
//! Per-plug-point trait surfaces live under [`surfaces`]:
//!
//! - [`surfaces::custom_data`]: custom data type plug-point.
//! - [`surfaces::actor`]: plug-in actor (`DataActor`-shaped) plug-point.
//! - [`surfaces::strategy`]: plug-in strategy (`Strategy`-shaped) plug-point.
//! - [`surfaces::controller`]: controller plug-point with prepare hooks and
//!   runtime strategy-control host services.
//!
//! Host-side loading lives behind the `host` feature and uses `libloading`.

/// ABI version of the plug-in contract.
///
/// The host refuses to load a plug-in whose [`PluginManifest::abi_version`]
/// does not match this value. The plug-in surface is unreleased and unstable,
/// so this value remains `1` during alpha and does not promise compatibility
/// between Nautilus versions. Rebuild plug-in cdylibs against the matching
/// host version.
///
/// [`PluginManifest::abi_version`]: crate::manifest::PluginManifest::abi_version
pub const NAUTILUS_PLUGIN_ABI_VERSION: u32 = 1;

/// Schema version for [`manifest::PluginBuildId`].
pub const PLUGIN_BUILD_ID_VERSION: u32 = 1;

/// Name of the single `extern "C"` entry symbol every plug-in cdylib must export.
///
/// The host looks up this symbol via `libloading::Symbol` after `dlopen`.
pub const NAUTILUS_PLUGIN_INIT_SYMBOL: &[u8] = b"nautilus_plugin_init";

pub mod boundary;
pub mod host;
pub mod manifest;
pub mod panic;
pub mod surfaces;

#[cfg(feature = "host")]
pub mod bridge;

#[cfg(feature = "host")]
pub mod loader;

mod macros;
mod normalize;

pub use boundary::{BorrowedStr, OwnedBytes, PluginError, PluginErrorCode, PluginResult, Slice};
pub use host::{ControllerHostContext, ControllerHostVTable, HostContext, HostVTable};
pub use manifest::{
    ActorRegistration, ControllerRegistration, CustomDataRegistration, PluginBuildId, PluginInitFn,
    PluginManifest, StrategyRegistration,
};
#[cfg(feature = "host")]
pub use manifest::{
    ValidatedActorRegistration, ValidatedActorVTable, ValidatedControllerRegistration,
    ValidatedControllerVTable, ValidatedCustomDataRegistration, ValidatedCustomDataVTable,
    ValidatedPluginManifest, ValidatedStrategyRegistration, ValidatedStrategyVTable,
};
pub use surfaces::{
    actor::PluginActor,
    controller::PluginController,
    custom_data::{PluginCustomData, PluginCustomDataRef},
    strategy::PluginStrategy,
};

/// Re-exports that plug-in authors typically want in scope.
pub mod prelude {
    pub use crate::{
        BorrowedStr, ControllerHostContext, ControllerHostVTable, HostContext, HostVTable,
        NAUTILUS_PLUGIN_ABI_VERSION, PluginActor, PluginBuildId, PluginController,
        PluginCustomData, PluginCustomDataRef, PluginError, PluginErrorCode, PluginManifest,
        PluginResult, PluginStrategy, Slice,
    };
}