sdk.md

Oak SDK

Project Oak provides a Rust SDK with helper functions to facilitate interactions with the Oak Runtime from Rust code compiled to WebAssembly. This provides idiomatic Rust abstractions over the lower level WebAssembly interface.

This page gives a summary of the functionality available in this SDK; refer to the generated documentation for more detailed information.

oak_abi Crate

The oak_abi crate provides Rust definitions that correspond to the Oak ABI. This includes:

• extern "C" declarations of the low-level host functions provided by the ABI; the u32, u64 and usize integer types described in the Oak ABI definition are mapped to the Rust integer types with the same names.
• A Handle type alias for u64 channel handle values.
• Constants used on the ABI (such as the INVALID_HANDLE value).
• Enum types (generated from the master protocol buffer definitions) for operation and channel status values.
• Generated Rust code corresponding to protocol buffer message types that are used as part of the Oak ABI.

oak Crate

The majority of the Oak Rust SDK is provided by the top-level oak crate. This includes wrapper functions for all of the host functions provided by the Oak ABI, using Rust types for easier use.

• Status values are returned as oak::OakStatus enum values rather than i32 values.
• Channel handles are held in the ReadHandle or WriteHandle wrapper structs for handles whose directionality is known.
• Read channel readiness is handled with Vec<oak::ReadHandle> and Vec<oak::ChannelReadStatus> types rather than raw memory.
• Channel read operations automatically re-size the outputs to accommodate the contents of read messages.

The oak crate also provides the oak::set_panic_hook() helper, to ensure that Rust panics are logged.

oak::io Module

The oak::io module provides a higher level abstraction to allow Rust objects to be communicated between Nodes.

The oak::io::channel_create<T> function creates oak::io::Sender and oak::io::Receiver objects. These objects allow sending and receiving of values of type T, provided that T implements the oak::io::Encodable and oak::io::Decodable traits.

oak::rand Module

The oak::rand module provides an implementation of the rand::RngCore trait, to allow use of the rand crate in Oak code.

oak::grpc Module

The oak::grpc module holds functionality that is helpful for interacting with the outside world over gRPC, either via an explicitly created gRPC server pseudo-Node, or via an explicitly created gRPC client pseudo-Node.

An Oak Node that acts as a gRPC server typically implements the oak::grpc::ServerNode trait, which is used with the oak::run_event_loop() function to services gRPC requests in a loop, invoking the trait's invoke() method for each request.

oak::http Module

The oak::http module holds functionality that is helpful for interacting with the outside world over HTTP, via an explicitly created HTTP server pseudo-Node.

An Oak Node that acts as an HTTP server is used with the oak::run_event_loop() function to services HTTP requests in a loop, calling the Node::handle_command() method for each request.

oak::storage Module

The oak::storage module holds functionality that is helpful for interacting with an external provider of persistent storage.

oak::roughtime Module

The oak::roughtime module holds functionality for retrieving an approximate wall clock time via a consensus of Roughtime servers, as a Duration since the UNIX epoch.

oak::proto Module

The oak::proto module holds auto-generated submodules for dealing with protocol buffers.

oak::logger Module

The oak::logger module is a logging implementation for the Rust log facade, which uses a channel to a freshly-created logging pseudo-Node as the underlying logging mechanism.