Struct HandleBuilder

Source

pub struct HandleBuilder { /* private fields */ }

Expand description

Builder used to set all the parameters to create a NoSQL Handle.

See Configuring the SDK for a detailed description of creating configurations for various Oracle NoSQL Database instance types (cloud, on-premises, etc.).

Implementations§

Source §

impl HandleBuilder

Source

pub fn new() -> Self

Create a new HandleBuilder struct.

The default HandleBuilder does not set an authentication method. Consider calling from_environment() to collect all parameters from the local environment by default.

Source

pub async fn build(self) -> Result<Handle, NoSQLError>

Build a new Handle.

Note: Internally, if the HandleBuilder contains a reference to an existing reqwest::Client, it will clone and use that. Otherwise, it will create a new reqwest::Client for its own internal use. See reqwest_client().

Source

pub fn from_environment(self) -> Result<Self, NoSQLError>

Gather configuration settings from the current envrionment.

This method will scan the process standard environment to collect and set the configuration parameters. The values can be overridden in code if this method is called first and other methods are called afterwards, for example:

   let builder = Handle::builder()
       .from_environment()?
       .cloud_auth_from_file("~/nosql_oci_config")?;

The following environment variables are used:

variable	description
`ORACLE_NOSQL_ENDPOINT`	The URL endpoint to use. See `HandleBuilder::endpoint()`.
`ORACLE_NOSQL_REGION`	The OCI region identifier. See `HandleBuilder::cloud_region()`.
`ORACLE_NOSQL_AUTH`	The auth mechanism. One of: `user`, `instance`, `resource`, `onprem`, `cloudsim`.
`ORACLE_NOSQL_AUTH_FILE`	For `user` auth, the path to the OCI config file (see `HandleBuilder::cloud_auth_from_file()`). For `onprem` auth, the path to the onprem user/password file (see `HandleBuilder::onprem_auth_from_file()`).
`ORACLE_NOSQL_CA_CERT`	For `onprem` auth, the path to the certificate file in `pem` format (see `HandleBuilder::add_cert_from_pemfile()`).
`ORACLE_NOSQL_ACCEPT_INVALID_CERTS`	For `onprem` auth, if this is set to `1` or `true`, do not check certificates (see `HandleBuilder::danger_accept_invalid_certs()`).

Source

pub fn endpoint(self, endpoint: &str) -> Result<Self, NoSQLError>

Set a specific endpoint connection to use.

This is typically used when specifying a local cloudsim instance, or an on-premises instance of the Oracle NoSQL Database Server. It can also be used to override Cloud Service Region endpoints, or to specify an endpoint for a new Region that has not been previously added to the SDK internally.

Examples:

    // Local cloudsim
    http://localhost:8080

    // Local on-premises server
    https://<database_host>:8080

    // Cloud service
    https://nosql.us-ashburn-1.oci.oraclecloud.com

Source

pub fn mode(self, mode: HandleMode) -> Result<Self, NoSQLError>

Set the mode for the handle.

Use HandleMode::Cloudsim to specify connection to a local cloudsim instance.

Use HandleMode::Onprem when connecting to an on-premises NoSQL Server.

By default, HandleBuilder assumes HandleMode::Cloud.

Source

pub fn cloud_auth_from_file(self, config_file: &str) -> Result<Self, NoSQLError>

Specify an OCI config file to use with user-based authentication.

This method allows the use of a file other than the default ~/.oci/config file. See SDK and CLI Configuration File for details. This method assumes the use of the "DEFAULT" profile.

Source

pub fn cloud_auth_from_file_with_profile( self, config_file: &str, profile: &str, ) -> Result<Self, NoSQLError>

Specify an OCI config file to use with user-based authentication.

This method allows the use of a file other than the default ~/.oci/config file. See SDK and CLI Configuration File for details.

Source

pub fn cloud_auth_from_instance(self) -> Result<Self, NoSQLError>

Specify using OCI Instance Principal for authentication.

Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. If the application is running on an OCI compute instance in the Oracle Cloud, the SDK can make use of the instance environment to determine its credentials (no config file is required). Each compute instance has its own identity, and it authenticates using the certificates that are added to it. See Calling Services from an Instance for prerequisite steps to set up Instance Principal.

Source

pub fn cloud_auth_from_resource(self) -> Result<Self, NoSQLError>

Specify using OCI Resource Principal for authentication.

Resource Principal is an IAM service feature that enables the resources to be authorized actors (or principals) to perform actions on service resources. You may use Resource Principal when calling Oracle NoSQL Database Cloud Service from other Oracle Cloud service resources such as Functions. See Accessing Other Oracle Cloud Infrastructure Resources from Running Functions for how to set up Resource Principal.

Source

pub fn cloud_region(self, region: &str) -> Result<Self, NoSQLError>

Specify a region identifier for the NoSQL Cloud Service.

This method is only required if using cloud user file-based authentication and the given config file does not have a region specification. The value should be a cloud-standard identifier for the region, such as us-ashburn-1. For more information on regions, see Regions and Availability Domains.

The NoSQL rust SDK maintains an internal list of regions where the NoSQL service is available. The region identifier passed to this method is validated against the internal list. If the region identifier is not found, it is then compared to the region metadata contained in the OCI_REGION_METADATA environment variable (if set), and to region metadata that may exist in a ~/.oci/regions-config.json file. See Adding Regions for details of these settings. In this way, new regions where NoSQL has been added may be used without needing to update to the latest NoSQL rust SDK.

Source

pub fn onprem_auth( self, username: &str, passwd: &str, ) -> Result<Self, NoSQLError>

Specify credentials for use with a secure On-premises NoSQL Server.

When using a secure server, a username and password are required. Use this method to specify the values.

Calling this method will also internally set the HandleMode to Onprem.

Source

pub fn onprem_auth_from_file(self, filename: &str) -> Result<Self, NoSQLError>

Specify credentials for use with a secure On-premises NoSQL Server from a local file.

When using a secure server, a username and password are required. Use this method to specify the values from a file. The format of the file is one value per line, using a key=value pair syntax, such as:

 username=testuser
 password=1234567

Calling this method will also internally set the HandleMode to Onprem.

Source

pub fn add_cert_from_pemfile(self, pemfile: &str) -> Result<Self, NoSQLError>

Add a certificate to use for on-premises https connections from a file.

The file must contain an x509 certificate in PEM file format.

Source

pub fn add_cert(self, cert: Certificate) -> Result<Self, NoSQLError>

Add a certificate to use for on-premises https connections.

Source

pub fn danger_accept_invalid_certs( self, accept_invalid_certs: bool, ) -> Result<Self, NoSQLError>

Allow https connection without validating certificates.

Warning: This is only recommended for local testing purposes. Its use is insecure. See reqwest::ClientBuilder::danger_accept_invalid_certs() for details.

Source

pub fn reqwest_client(self, client: &Client) -> Result<Self, NoSQLError>

Specify a reqwest::Client to use for all http/s connections.

By default, the NoSQL Handle creates an internal reqwest::Client to use for all communications. If your application already has a reqwest Client, you can pass that into the HandleBuilder to avoid creating multiple connection pools.

Source