Trait Service 

pub trait Service:
    Send
    + Sync
    + Debug
    + Unpin
    + 'static {
    type Reader: Read;
    type Writer: Write;
    type Lister: List;
    type Deleter: Delete;
    type Copier: Copy;
    type Composer: Compose;

    // Required methods
    fn info(&self) -> ServiceInfo;
    fn capability(&self) -> Capability;
    fn create_dir(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpCreateDir,
    ) -> impl Future<Output = Result<RpCreateDir>> + MaybeSend;
    fn stat(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpStat,
    ) -> impl Future<Output = Result<RpStat>> + MaybeSend;
    fn read(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpRead,
    ) -> Result<Self::Reader>;
    fn write(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpWrite,
    ) -> Result<Self::Writer>;
    fn delete(&self, ctx: &OperationContext) -> Result<Self::Deleter>;
    fn list(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpList,
    ) -> Result<Self::Lister>;
    fn copy(
        &self,
        ctx: &OperationContext,
        from: &str,
        to: &str,
        args: OpCopy,
    ) -> Result<Self::Copier>;
    fn rename(
        &self,
        ctx: &OperationContext,
        from: &str,
        to: &str,
        args: OpRename,
    ) -> impl Future<Output = Result<RpRename>> + MaybeSend;
    fn presign(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpPresign,
    ) -> impl Future<Output = Result<RpPresign>> + MaybeSend;

    // Provided methods
    fn compose(
        &self,
        _ctx: &OperationContext,
        _to: &str,
        _args: OpCompose,
    ) -> Result<Self::Composer> { ... }
    fn restore(
        &self,
        _ctx: &OperationContext,
        _path: &str,
        _args: OpRestore,
    ) -> impl Future<Output = Result<RpRestore>> + MaybeSend { ... }
}

Foundational trait for storage services.

Every storage service (or backend) in OpenDAL implements Service. Services and layers must implement every operation in this trait and declare their capabilities. This allows callers to detect unsupported operations.

Operations

• An operator normalizes paths before passing them to a Service. Relative to the configured root:
  • / represents the root.
  • A path ending with / represents a directory.
  • Any other path represents a file.
• Services report their supported operation set through Service::capability.
• The OperationContext carries layer-composed runtime resources for each operation.

Required Associated Types

type Reader: Read

Reader returned by read.

type Writer: Write

Writer returned by write.

type Lister: List

Lister returned by list.

type Deleter: Delete

Deleter returned by delete.

type Copier: Copy

Copier returned by copy.

type Composer: Compose

Composer returned by compose.

Required Methods

fn info(&self) -> ServiceInfo

Return the immutable identity and configuration for this service.

fn capability(&self) -> Capability

Return the capability of this service stack.

Layers may affect a service’s capabilities, so callers should use this value for the current stack instead of assuming the backend’s native capability.

fn create_dir( &self, ctx: &OperationContext, path: &str, args: OpCreateDir, ) -> impl Future<Output = Result<RpCreateDir>> + MaybeSend

Invoke the create operation on the specified path.

Requires Capability::create_dir.

Behavior

• path is a normalized directory path.
• Creating an existing directory should succeed.

fn stat( &self, ctx: &OperationContext, path: &str, args: OpStat, ) -> impl Future<Output = Result<RpStat>> + MaybeSend

Invoke the stat operation on the specified path.

Requires Capability::stat.

Behavior

• / means the service root.
• A path ending with / stats a directory.
• Returned metadata must set mode and content_length.

fn read( &self, ctx: &OperationContext, path: &str, args: OpRead, ) -> Result<Self::Reader>

Invoke the read operation on the specified path.

Requires Capability::read.

Behavior

• path is a normalized file path.
• Range I/O is handled by the returned reader.

fn write( &self, ctx: &OperationContext, path: &str, args: OpWrite, ) -> Result<Self::Writer>

Invoke the write operation on the specified path.

Requires Capability::write.

Behavior

• path is a normalized file path.

fn delete(&self, ctx: &OperationContext) -> Result<Self::Deleter>

Invoke the delete operation.

Requires Capability::delete.

Behavior

• The returned deleter handles one or more delete requests.
• Deleting a missing path should succeed unless a condition requires a live target.

fn list( &self, ctx: &OperationContext, path: &str, args: OpList, ) -> Result<Self::Lister>

Invoke the list operation on the specified path.

Requires Capability::list.

Behavior

• path is a normalized directory path or prefix.
• Listing a non-existing directory should return an empty stream.

fn copy( &self, ctx: &OperationContext, from: &str, to: &str, args: OpCopy, ) -> Result<Self::Copier>

Invoke the copy operation on the specified from path and to path.

Requires Capability::copy.

Behavior

• from and to are normalized file paths.
• Copying to an existing file should overwrite and truncate it.

fn rename( &self, ctx: &OperationContext, from: &str, to: &str, args: OpRename, ) -> impl Future<Output = Result<RpRename>> + MaybeSend

Invoke the rename operation on the specified from path and to path.

Requires Capability::rename.

Behavior

• from and to are normalized file paths.

fn presign( &self, ctx: &OperationContext, path: &str, args: OpPresign, ) -> impl Future<Output = Result<RpPresign>> + MaybeSend

Invoke the presign operation on the specified path.

Requires Capability::presign and the matching presign operation capability.

Provided Methods

fn compose( &self, _ctx: &OperationContext, _to: &str, _args: OpCompose, ) -> Result<Self::Composer>

Invoke the compose operation for the specified destination path.

Requires Capability::compose.

fn restore( &self, _ctx: &OperationContext, _path: &str, _args: OpRestore, ) -> impl Future<Output = Result<RpRestore>> + MaybeSend

Invoke the restore operation on the specified path.

Requires Capability::restore.

Behavior

• path is a normalized file path.
• Without a version, restore reverses the latest recoverable deletion state.
• With a version, restore promotes that historical version to the current version.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl Service for ()

Dummy implementation of service.

type Reader = ()

type Writer = ()

type Lister = ()

type Deleter = ()

type Copier = ()

type Composer = ()

fn info(&self) -> ServiceInfo

fn capability(&self) -> Capability

async fn create_dir( &self, _: &OperationContext, _: &str, _: OpCreateDir, ) -> Result<RpCreateDir>

async fn stat(&self, _: &OperationContext, _: &str, _: OpStat) -> Result<RpStat>

fn read(&self, _: &OperationContext, _: &str, _: OpRead) -> Result<Self::Reader>

fn write( &self, _: &OperationContext, _: &str, _: OpWrite, ) -> Result<Self::Writer>

fn delete(&self, _: &OperationContext) -> Result<Self::Deleter>

fn list(&self, _: &OperationContext, _: &str, _: OpList) -> Result<Self::Lister>

fn copy( &self, _: &OperationContext, _: &str, _: &str, _: OpCopy, ) -> Result<Self::Copier>

async fn rename( &self, _: &OperationContext, _: &str, _: &str, _: OpRename, ) -> Result<RpRename>

async fn presign( &self, _: &OperationContext, _: &str, _: OpPresign, ) -> Result<RpPresign>

impl<T: ServiceDyn + ?Sized> Service for Arc<T>

Implement Service for type-erased services so they use the same API.

type Reader = Box<dyn ReadDyn>

type Writer = Box<dyn WriteDyn>

type Lister = Box<dyn ListDyn>

type Deleter = Box<dyn DeleteDyn>

type Copier = Box<dyn CopyDyn>

type Composer = Box<dyn ComposeDyn>

fn info(&self) -> ServiceInfo

fn capability(&self) -> Capability

async fn create_dir( &self, ctx: &OperationContext, path: &str, args: OpCreateDir, ) -> Result<RpCreateDir>

async fn stat( &self, ctx: &OperationContext, path: &str, args: OpStat, ) -> Result<RpStat>

fn read( &self, ctx: &OperationContext, path: &str, args: OpRead, ) -> Result<Reader>

fn write( &self, ctx: &OperationContext, path: &str, args: OpWrite, ) -> Result<Writer>

fn delete(&self, ctx: &OperationContext) -> Result<Deleter>

fn list( &self, ctx: &OperationContext, path: &str, args: OpList, ) -> Result<Lister>

fn copy( &self, ctx: &OperationContext, from: &str, to: &str, args: OpCopy, ) -> Result<Copier>

fn compose( &self, ctx: &OperationContext, to: &str, args: OpCompose, ) -> Result<Composer>

async fn rename( &self, ctx: &OperationContext, from: &str, to: &str, args: OpRename, ) -> Result<RpRename>

async fn restore( &self, ctx: &OperationContext, path: &str, args: OpRestore, ) -> Result<RpRestore>

async fn presign( &self, ctx: &OperationContext, path: &str, args: OpPresign, ) -> Result<RpPresign>

Implementors