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;

    // 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, Error>> + MaybeSend;
    fn stat(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpStat,
    ) -> impl Future<Output = Result<RpStat, Error>> + MaybeSend;
    fn read(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpRead,
    ) -> Result<Self::Reader, Error>;
    fn write(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpWrite,
    ) -> Result<Self::Writer, Error>;
    fn delete(&self, ctx: &OperationContext) -> Result<Self::Deleter, Error>;
    fn list(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpList,
    ) -> Result<Self::Lister, Error>;
    fn copy(
        &self,
        ctx: &OperationContext,
        from: &str,
        to: &str,
        args: OpCopy,
        opts: OpCopier,
    ) -> Result<Self::Copier, Error>;
    fn rename(
        &self,
        ctx: &OperationContext,
        from: &str,
        to: &str,
        args: OpRename,
    ) -> impl Future<Output = Result<RpRename, Error>> + MaybeSend;
    fn presign(
        &self,
        ctx: &OperationContext,
        path: &str,
        args: OpPresign,
    ) -> impl Future<Output = Result<RpPresign, Error>> + 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.

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, Error>> + 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, Error>> + 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, Error>

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, Error>

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, Error>

Invoke the delete operation.

Requires Capability::delete.

Behavior

• The returned deleter handles one or more delete requests.
• Deleting a missing path should succeed.

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

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, opts: OpCopier, ) -> Result<Self::Copier, Error>

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, Error>> + 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, Error>> + MaybeSend

Invoke the presign operation on the specified path.

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Service for ()

Dummy implementation of service.

type Reader = ()

type Writer = ()

type Lister = ()

type Deleter = ()

type Copier = ()

fn info(&self) -> ServiceInfo

fn capability(&self) -> Capability

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

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

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

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

fn delete( &self, _: &OperationContext, ) -> Result<<() as Service>::Deleter, Error>

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

fn copy( &self, _: &OperationContext, _: &str, _: &str, _: OpCopy, _: OpCopier, ) -> Result<<() as Service>::Copier, Error>

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

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

impl<T> Service for Arc<T>

where T: ServiceDyn + ?Sized,

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>

fn info(&self) -> ServiceInfo

fn capability(&self) -> Capability

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

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

fn read( &self, ctx: &OperationContext, path: &str, args: OpRead, ) -> Result<Box<dyn ReadDyn>, Error>

fn write( &self, ctx: &OperationContext, path: &str, args: OpWrite, ) -> Result<Box<dyn WriteDyn>, Error>

fn delete(&self, ctx: &OperationContext) -> Result<Box<dyn DeleteDyn>, Error>

fn list( &self, ctx: &OperationContext, path: &str, args: OpList, ) -> Result<Box<dyn ListDyn>, Error>

fn copy( &self, ctx: &OperationContext, from: &str, to: &str, args: OpCopy, opts: OpCopier, ) -> Result<Box<dyn CopyDyn>, Error>

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

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

Implementors