Struct Capabilities

pub struct Capabilities { /* private fields */ }

Capabilities are used to limit what a user can do to the system.

Capabilities are split into 4 categories:

• Scripting: Whether or not the user can execute scripts
• Guest access: Whether or not a non-authenticated user can execute queries on the system when authentication is enabled.
• Functions: Whether or not the user can execute certain functions
• Network: Whether or not the user can access certain network addresses

Capabilities are configured globally. By default, capabilities are configured as:

• Scripting: false
• Guest access: false
• Functions: All functions are allowed
• Network: No network address is allowed nor denied, hence all network addresses are denied unless explicitly allowed

The capabilities are defined using allow/deny lists for fine-grained control.

Filtering functions and net-targets.

The filtering of net targets and functions is done with an allow/deny list. These list can either match everything, nothing or a given list.

By default every function and net-target is disallowed. For a function or net target to be allowed it must match the allow-list and not match the deny-list. This means that if for example a function is both in the allow-list and in the deny-list it will be disallowed.

With the combination of both these lists you can filter subgroups. For example:

Capabilities::none()
    .with_allow_function("http::*")?
    .with_deny_function("http::post")?

Will allow all and only all http::* functions except the function http::post.

Examples:

• Allow all functions: --allow-funcs
• Allow all functions except http.*: --allow-funcs --deny-funcs 'http.*'
• Allow all network addresses except AWS metadata endpoint: --allow-net --deny-net='169.254.169.254'

Examples

Create a new instance, and allow all capabilities

let capabilities = Capabilities::all();
let config = Config::default().capabilities(capabilities);
let db = Surreal::new::<File>(("temp.db", config)).await?;

Create a new instance, and allow certain functions

let capabilities = Capabilities::default()
    .with_deny_function("http::*")?;
let config = Config::default().capabilities(capabilities);
let db = Surreal::new::<File>(("temp.db", config)).await?;

Implementations

impl Capabilities

pub fn new() -> Self

Create a builder with default capabilities enabled.

Default capabilities enables live query notifications and all (non-scripting) functions.

pub fn all() -> Self

Create a builder with all capabilities enabled.

pub fn none() -> Self

Create a builder with all capabilities disabled.

pub fn with_scripting(self, enabled: bool) -> Self

Set whether to enable the embedded javascript scripting runtime.

pub fn with_guest_access(self, enabled: bool) -> Self

Set whether to allow non-authenticated users to execute queries when authentication is enabled.

pub fn with_live_query_notifications(self, enabled: bool) -> Self

Set wether to enable live query notifications.

pub fn allow_all_functions(&mut self) -> &mut Self

Set the allow list to allow all functions

pub fn with_allow_all_functions(self) -> Self

Set the allow list to allow all functions

pub fn deny_all_functions(&mut self) -> &mut Self

Set the deny list to deny all functions

pub fn with_deny_all_function(self) -> Self

Set the deny list to deny all functions

pub fn allow_none_functions(&mut self) -> &mut Self

Set the allow list to allow no function

pub fn with_allow_none_functions(self) -> Self

Set the allow list to allow no function

pub fn deny_none_functions(&mut self) -> &mut Self

Set the deny list to deny no function

pub fn with_deny_none_function(self) -> Self

Set the deny list to deny no function

pub fn allow_function<S: AsRef<str>>( &mut self, func: S, ) -> Result<&mut Self, ParseFuncTargetError>

Add a function to the allow lists

Adding a function to the allow list overwrites previously set allow-all or allow-none filters.

pub fn with_allow_function<S: AsRef<str>>( self, func: S, ) -> Result<Self, ParseFuncTargetError>

Add a function to the allow lists

Adding a function to the allow list overwrites previously set allow-all or allow-none filters.

pub fn deny_function<S: AsRef<str>>( &mut self, func: S, ) -> Result<&mut Self, ParseFuncTargetError>

Add a function to the deny lists

Adding a function to the deny list overwrites previously set deny-all or deny-none filters.

pub fn with_deny_function<S: AsRef<str>>( self, func: S, ) -> Result<Self, ParseFuncTargetError>

Add a function to the deny lists

Adding a function to the deny list overwrites previously set deny-all or deny-none filters.

pub fn allow_all_net_targets(&mut self) -> &mut Self

Set the allow list to allow all net targets

pub fn with_allow_all_net_targets(self) -> Self

Set the allow list to allow all net targets

pub fn deny_all_net_targets(&mut self) -> &mut Self

Set the deny list to deny all net targets

pub fn with_deny_all_net_target(self) -> Self

Set the deny list to deny all net targets

pub fn allow_none_net_targets(&mut self) -> &mut Self

Set the allow list to allow no net targets

pub fn with_allow_none_net_targets(self) -> Self

Set the allow list to allow no net targets

pub fn deny_none_net_targets(&mut self) -> &mut Self

Set the deny list to deny no net targets

pub fn with_deny_none_net_target(self) -> Self

Set the deny list to deny no net targets

pub fn allow_net_target<S: AsRef<str>>( &mut self, func: S, ) -> Result<&mut Self, ParseNetTargetError>

Add a net target to the allow lists

Adding a net target to the allow list overwrites previously set allow-all or allow-none filters.

pub fn with_allow_net_target<S: AsRef<str>>( self, func: S, ) -> Result<Self, ParseNetTargetError>

Add a net target to the allow lists

Adding a net target to the allow list overwrites previously set allow-all or allow-none filters.

pub fn deny_net_target<S: AsRef<str>>( &mut self, func: S, ) -> Result<&mut Self, ParseNetTargetError>

Add a net target to the deny lists

Adding a net target to the deny list overwrites previously set deny-all or deny-none filters.

pub fn with_deny_net_target<S: AsRef<str>>( self, func: S, ) -> Result<Self, ParseNetTargetError>

Add a net target to the deny lists

Adding a net target to the deny list overwrites previously set deny-all or deny-none filters.

Trait Implementations

impl Clone for Capabilities

fn clone(&self) -> Capabilities

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Capabilities

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Capabilities

fn default() -> Self

Returns the “default value” for a type.