fidius_core/
python_descriptor.rs

1// Copyright 2026 Colliery, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
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//! Compile-time descriptor of a fidius interface used by the Python loader.
16//!
17//! The cdylib path doesn't need any of this: the dylib carries its own
18//! `PluginRegistry` + vtable that the host introspects at load time. A
19//! Python plugin doesn't have a vtable; the host needs an out-of-band hint
20//! about which method names exist on the trait, in what order, and with
21//! which wire mode. The `#[plugin_interface]` macro emits a
22//! `PythonInterfaceDescriptor` const into its companion module to provide
23//! exactly that.
24//!
25//! The descriptor is `'static`-shaped (string slices, slice of structs) so
26//! it can sit in the binary's `.rodata` and be referenced freely.
27
28/// Static descriptor for one fidius interface, consumed by the Python
29/// loader to validate and dispatch into a Python plugin.
30#[derive(Debug, Clone, Copy)]
31pub struct PythonInterfaceDescriptor {
32    /// Trait name, used for diagnostics only.
33    pub interface_name: &'static str,
34    /// Same hash the cdylib path baked into its `PluginDescriptor`. The
35    /// Python plugin's `__interface_hash__` constant must match this.
36    pub interface_hash: u64,
37    /// Methods in declaration order — the index here lines up with the
38    /// vtable index the cdylib path uses for the same trait. The Python
39    /// loader looks up callables in this order so `call_method(i, ...)`
40    /// dispatches to the right Python function.
41    pub methods: &'static [PythonMethodDesc],
42}
43
44/// One method on the interface.
45#[derive(Debug, Clone, Copy)]
46pub struct PythonMethodDesc {
47    /// Function name to look up in the Python plugin module.
48    pub name: &'static str,
49    /// Whether this method uses raw byte-passthrough wire mode
50    /// (`#[wire(raw)]`). Determines whether the dispatcher routes through
51    /// `call_method_raw` (raw bytes both sides) or `call_method` (typed
52    /// args via JSON conversion).
53    pub wire_raw: bool,
54}
fidius_core/python_descriptor.rs

fidius_core/
python_descriptor.rs
