ordinary_config/app/function/
mod.rs

1// Copyright (C) 2026 The Ordinary Authors.
2//
3// SPDX-License-Identifier: BSD-3-Clause
4
5use crate::{Bindgen, StoredCache};
6use ordinary_types::Kind;
7use serde::{Deserialize, Serialize};
8
9/// Configuration parameters for Ordinary Functions.
10#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
11#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
12#[derive(Deserialize, Serialize, Debug, Clone, Default)]
13pub struct FunctionConfig {
14    /// Foreign function interface config
15    #[serde(skip_serializing_if = "Option::is_none")]
16    #[serde(default)]
17    pub ffi: Option<FunctionFfi>,
18    /// Refers to the template config in another location
19    #[serde(skip_serializing_if = "Option::is_none")]
20    #[serde(default, rename = "ref")]
21    pub r#ref: Option<String>,
22
23    /// Function name. Must be unique.
24    #[serde(skip_serializing_if = "Option::is_none")]
25    #[serde(default)]
26    pub name: Option<String>,
27
28    #[serde(skip_serializing_if = "Option::is_none")]
29    #[serde(default)]
30    pub readonly: Option<bool>,
31
32    /// which language the input binding WebAssembly
33    /// Component should be compiled _from_.
34    ///
35    /// Note: because the bindings are compiled _to_
36    /// a WebAssembly Component, with a companion WIT
37    /// file, the resulting bindings can be used by any
38    /// language that has WIT support.
39    ///
40    /// i.e. bindings compiled from Rust can be plugged
41    /// into a Golang WebAssembly component.
42    ///
43    /// **Important**: if your FFI serialization format
44    /// is JSON, or you are comfortable writing your own
45    /// `FlexBuffer` vector accessors it is not necessary
46    /// to generate the bindings (other than for reference
47    /// in the `FlexBuffer` vector accessing case).
48    #[serde(skip_serializing_if = "Option::is_none")]
49    #[serde(default)]
50    pub bindgen: Option<Bindgen>,
51    /// language for which the function builds
52    #[serde(skip_serializing_if = "Option::is_none")]
53    #[serde(default)]
54    pub toolchain: Option<FunctionToolchain>,
55    /// build scripts for ensuring the WebAssembly components
56    /// are composed properly at build time.
57    #[serde(skip_serializing_if = "Option::is_none")]
58    #[serde(default)]
59    pub build: Option<Vec<Vec<String>>>,
60    /// path to the WASM component binary
61    #[serde(skip_serializing_if = "Option::is_none")]
62    #[serde(default)]
63    pub bin: Option<String>,
64
65    /// What to check the token fields against. If unset
66    /// function is public.
67    #[serde(skip_serializing_if = "Option::is_none")]
68    #[serde(default)]
69    pub protected: Option<bool>,
70    /// Which Ordinary Application resources and
71    /// host extensions this function has access to.
72    #[serde(skip_serializing_if = "Option::is_none")]
73    #[serde(default)]
74    pub access: Option<Vec<FunctionAccessPermission>>,
75
76    /// Input definition for the action.
77    #[serde(skip_serializing_if = "Option::is_none")]
78    #[serde(default)]
79    pub input: Option<Kind>,
80    /// Output definition for the action.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    #[serde(default)]
83    pub output: Option<Kind>,
84
85    /// Persistent result cache configuration for `readonly`
86    /// functions.
87    #[serde(skip_serializing_if = "Option::is_none")]
88    #[serde(default)]
89    pub cache: Option<StoredCache>,
90
91    /// List of build time environment variables.
92    ///
93    /// format in template: `{{ YOUR_VAR }}`
94    #[serde(skip_serializing_if = "Option::is_none")]
95    #[serde(default)]
96    pub variables: Option<Vec<String>>,
97
98    /// Max duration for the action.
99    ///
100    /// Unit: seconds
101    #[serde(skip_serializing_if = "Option::is_none")]
102    #[serde(default)]
103    pub timeout: Option<u16>,
104}
105
106impl FunctionConfig {
107    #[allow(clippy::single_match)]
108    pub fn load_bindgen(&mut self) {
109        let function_name = self.name_validated().to_owned();
110
111        match self.bindgen {
112            Some(Bindgen::V1Rust) => {
113                self.ffi = Some(FunctionFfi {
114                    version: FunctionFfiVersion::V1,
115                    serialization: FunctionFfiSerialization::FlexBufferVector,
116                });
117
118                let mut build = self.build.clone().unwrap_or_default();
119                build.push(vec![
120                    "sh".into(),
121                    format!(".ordinary/{function_name}/build.sh"),
122                ]);
123                self.build = Some(build);
124                self.bin = Some(format!(".ordinary/{function_name}/function.wasm"));
125            }
126            _ => (),
127        }
128    }
129
130    /// ## Panics
131    ///
132    /// This method panics if the `ffi` field has not been validated to be present
133    #[must_use]
134    pub fn ffi_validated(&self) -> &FunctionFfi {
135        self.ffi.as_ref().expect("FFI should be present")
136    }
137
138    /// ## Panics
139    ///
140    /// This method panics if the `name` field has not been validated to be present
141    #[must_use]
142    pub fn name_validated(&self) -> &str {
143        self.name.as_deref().expect("Name should be present")
144    }
145
146    /// ## Panics
147    ///
148    /// This method panics if the `accepts` field has not been validated to be present
149    #[must_use]
150    pub fn input_validated(&self) -> &Kind {
151        self.input.as_ref().expect("Input should be present")
152    }
153
154    /// ## Panics
155    ///
156    /// This method panics if the `returns` field has not been validated to be present
157    #[must_use]
158    pub fn output_validated(&self) -> &Kind {
159        self.output.as_ref().expect("Output should be present")
160    }
161}
162
163#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
164#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
165#[derive(Deserialize, Serialize, Debug, Clone, Default)]
166pub enum FunctionFfiVersion {
167    #[default]
168    V1,
169}
170
171/// Input/output serialization for module and host functions.
172#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
173#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
174#[derive(Deserialize, Serialize, Debug, Clone, Default)]
175pub enum FunctionFfiSerialization {
176    #[default]
177    FlexBufferVector,
178    Json,
179}
180
181#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
182#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
183#[derive(Deserialize, Serialize, Debug, Clone, Default)]
184pub struct FunctionFfi {
185    pub version: FunctionFfiVersion,
186    pub serialization: FunctionFfiSerialization,
187}
188
189/// The language toolchain the function is built with.
190#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
191#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
192#[derive(Deserialize, Serialize, Debug, Clone, Default)]
193pub enum FunctionToolchain {
194    /// Function is written in the Rust programming language.
195    ///
196    /// Templates using [Askama](https://askama.rs/en/stable/).
197    #[default]
198    #[serde(rename = "rust")]
199    Rs,
200    /// Function is written in the C programming language.
201    #[serde(rename = "c")]
202    C,
203    /// Function is written in JavaScript.
204    #[serde(rename = "js")]
205    Js,
206    /// Function is written in TypeScript.
207    #[serde(rename = "ts")]
208    Ts,
209    /// Function is written in the Go programming language.
210    ///
211    /// Templates using Go templates.
212    #[serde(rename = "go")]
213    Go,
214    // todo: C,
215    // todo: Zig,
216    // todo: Cs,
217    // todo: Lua,
218    // todo: Cpp,
219}
220
221impl FunctionToolchain {
222    #[must_use]
223    pub fn as_str(&self) -> &'static str {
224        match self {
225            Self::Rs => "rust",
226            Self::C => "c",
227            Self::Js => "js",
228            Self::Ts => "ts",
229            Self::Go => "go",
230        }
231    }
232}
233
234#[cfg(feature = "cli")]
235impl std::fmt::Display for FunctionToolchain {
236    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
237        match self {
238            Self::Rs => write!(f, "rust"),
239            Self::C => write!(f, "c"),
240            Self::Js => write!(f, "js"),
241            Self::Ts => write!(f, "ts"),
242            Self::Go => write!(f, "go"),
243        }
244    }
245}
246
247#[cfg(feature = "cli")]
248impl clap::ValueEnum for FunctionToolchain {
249    fn value_variants<'a>() -> &'a [Self] {
250        &[Self::Rs, Self::C, Self::Go, Self::Js, Self::Ts]
251    }
252
253    fn to_possible_value(&self) -> Option<clap::builder::PossibleValue> {
254        match self {
255            Self::Rs => Some(clap::builder::PossibleValue::new("rust")),
256            Self::C => Some(clap::builder::PossibleValue::new("c")),
257            Self::Js => Some(clap::builder::PossibleValue::new("js")),
258            Self::Ts => Some(clap::builder::PossibleValue::new("ts")),
259            Self::Go => Some(clap::builder::PossibleValue::new("go")),
260        }
261    }
262}
263
264/// Model operations that an function is allowed to make.
265#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
266#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
267#[derive(Deserialize, Serialize, Debug, Clone, PartialOrd, PartialEq, Eq, Hash)]
268pub enum FunctionAccessDatabaseOps {
269    /// Can create an item for this model.
270    Insert,
271    /// Can get an item for this model by UUID or Index.
272    Get,
273    /// Can query an item for this model by queryable field.
274    Query,
275    /// Can update an item for this model.
276    Update,
277    /// Can delete an item for this model.
278    Delete,
279}
280
281/// Auth operations that a function can make.
282#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
283#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
284#[derive(Deserialize, Serialize, Debug, Clone)]
285pub enum FunctionAccessAuthOps {
286    /// Allows the function the ability to set
287    /// a user's access token fields/claims.
288    SetClaims,
289}
290
291/// Defines access permissions that an Ordinary
292/// Function can configure.
293#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
294#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
295#[derive(Deserialize, Serialize, Debug, Clone)]
296pub enum FunctionAccessPermission {
297    /// Provides the function access to a given model.
298    Database {
299        /// Name of the model.
300        model: String,
301        /// List of allowed operations that the function
302        /// can take on the model.
303        ops: Vec<FunctionAccessDatabaseOps>,
304    },
305    /// Provides the function access to Ordinary Auth.
306    Auth {
307        /// Which operations the function is allowed to take.
308        ops: Vec<FunctionAccessAuthOps>,
309    },
310    /// provides functions access to Ordinary Extensions
311    /// that its parent app has access to.
312    Extension {
313        /// name of the extension the function has access to
314        name: String,
315        /// names of the ops that the function has access to
316        ops: Vec<String>,
317    },
318}
ordinary_config/app/function/mod.rs

ordinary_config/app/function/
mod.rs
