Crate opendal_core

Expand description

§Apache OpenDAL™ Core

opendal-core contains the storage abstraction, operator APIs, extension traits, and shared infrastructure used by Apache OpenDAL™.

Most applications should depend on the opendal facade. The facade re-exports the core APIs and wires optional service, layer, executor, and HTTP transport crates behind feature flags.

Depend on opendal-core directly when implementing an OpenDAL service or layer, building a minimal integration from the split crates, or managing service registration and HTTP transport explicitly.

§Quick start

The in-memory service is always available:

cargo add opendal-core

use opendal_core::services;
use opendal_core::Operator;
use opendal_core::Result;

fn build_operator() -> Result<Operator> {
    Operator::new(services::Memory::default())
}

Storage services and optional layers live in separate opendal-service-* and opendal-layer-* crates. Applications using the facade can enable them through services-* and layers-* features instead.

§Compose split crates

Applications that depend on opendal-core directly compose storage and runtime behavior explicitly:

A service crate exports a builder that implements opendal_core::Builder. Pass the configured builder to Operator::new.
A layer crate exports a type that implements opendal_core::raw::Layer. Pass the configured layer to Operator::layer.
An HTTP transport crate exports an opendal_core::HttpTransport implementation. Wrap it in HttpTransporter and place it in the operator’s OperationContext.

For example, the following dependencies compose S3, retry, and the reqwest HTTP transport without the opendal facade:

cargo add opendal-core opendal-service-s3 opendal-layer-retry
cargo add opendal-http-transport-reqwest

use opendal_core::HttpTransporter;
use opendal_core::OperationContext;
use opendal_core::Operator;
use opendal_core::Result;
use opendal_http_transport_reqwest::ReqwestTransport;
use opendal_layer_retry::RetryLayer;
use opendal_service_s3::S3;

fn build_operator(builder: S3) -> Result<Operator> {
    let context = OperationContext::new()
        .with_http_transport(HttpTransporter::new(ReqwestTransport::default()));

    Ok(Operator::new(builder)?
        .with_context(context)
        .layer(RetryLayer::default()))
}

Configure builder for the target S3-compatible service before passing it to build_operator.

Operator::new uses the builder directly and does not require service registration. Call the service crate’s register_*_service function with OperatorRegistry::get() only when using scheme-driven construction through Operator::from_uri or Operator::via_iter.

§Documentation

§License

Licensed under the Apache License, Version 2.0.

Modules§

blockingblocking: blocking module provides blocking APIs for OpenDAL.
executors: executors module provides implementations for the Execute trait for widely used runtimes.
layers: Core layers used by opendal-core.
operator_futures: Futures provides the futures generated by Operator
options: Options module provides options definitions for operations.
raw: Raw modules provide raw APIs that used by underlying services
services: Built-in service support.

Structs§

Buffer: Buffer is a wrapper of contiguous Bytes and non-contiguous [Bytes].
BufferSink: BufferSink is the adapter of futures::Sink generated by Writer::into_sink
BufferStream: BufferStream is a stream of buffers, created by Reader::into_stream
Capability: Capability defines the supported operations and their constraints for a storage Operator.
Copier: Copier drives a long-running copy operation one step at a time.
DeleteInput: DeleteInput is the input for delete operations.
Deleter: Deleter is designed to continuously remove content from storage.
Entry: Entry represents an entry’s path and metadata.
Error: Error is the error struct returned by all opendal functions.
Executor: Executor that runs futures in background.
FuturesAsyncReader: FuturesAsyncReader is the adapter of AsyncRead, AsyncBufRead and AsyncSeek generated by Reader::into_futures_async_read.
FuturesAsyncWriter: FuturesIoAsyncWriter is the adapter of AsyncWrite for Writer.
FuturesBytesSink: FuturesBytesSink is the adapter of futures::Sink generated by Writer::into_bytes_sink.
FuturesBytesStream: FuturesBytesStream is the adapter of Stream generated by Reader::into_bytes_stream.
FuturesDeleteSink: FuturesDeleteSink is a sink that generated by Deleter
HttpBody: The streaming body returned by HttpTransporter.
HttpTransporter: Type-erased HTTP transport handle.
Lister: Lister lists entries at a given path asynchronously.
Metadata: Metadata contains all the information related to a specific path.
OperationContext: Composed resources passed from operator to services and layers.
Operator: The Operator serves as the entry point for all public asynchronous APIs.
OperatorInfo: Metadata for operator, users can use this metadata to get information of operator.
OperatorRegistry: Global registry that maps schemes to OperatorFactory functions.
OperatorUri: Parsed representation of an operator URI with normalized components.
Reader: Reader is designed to read data from given path in an asynchronous manner.
Writer: Writer is designed to write data into given path in an asynchronous manner.

Enums§

BytesRange: BytesRange carries a range of content.
EntryMode: EntryMode represents the mode.
ErrorKind: OpenDAL error categories.

Traits§

Builder: OpenDAL uses Builder to set up a service.
Configurator: OpenDAL uses Configurator to configure a service.
Execute: Execute trait is used to execute task in background.
HttpTransport: HTTP transport used by OpenDAL services.
IntoDeleteInput: IntoDeleteInput is a helper trait that makes it easier for users to play with Deleter.
IntoOperatorUri: Conversion trait that builds OperatorUri from various inputs.

Type Aliases§

OperatorFactory: Factory signature used to construct Operator from a URI and extra options.
Result: A specialized std::result::Result whose default error type is Error.