Trait opendal::raw::Accessor

pub trait Accessor: Send + Sync + Debug + Unpin + 'static {
    type Reader: Read;
    type Writer: Write;
    type Lister: List;
    type BlockingReader: BlockingRead;
    type BlockingWriter: BlockingWrite;
    type BlockingLister: BlockingList;

    // Required method
    fn info(&self) -> AccessorInfo;

    // Provided methods
    fn create_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpCreateDir
    ) -> Pin<Box<dyn Future<Output = Result<RpCreateDir>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn stat<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpStat
    ) -> Pin<Box<dyn Future<Output = Result<RpStat>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn read<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpRead
    ) -> Pin<Box<dyn Future<Output = Result<(RpRead, Self::Reader)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn write<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpWrite
    ) -> Pin<Box<dyn Future<Output = Result<(RpWrite, Self::Writer)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn delete<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpDelete
    ) -> Pin<Box<dyn Future<Output = Result<RpDelete>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn list<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpList
    ) -> Pin<Box<dyn Future<Output = Result<(RpList, Self::Lister)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn copy<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        from: &'life1 str,
        to: &'life2 str,
        args: OpCopy
    ) -> Pin<Box<dyn Future<Output = Result<RpCopy>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn rename<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        from: &'life1 str,
        to: &'life2 str,
        args: OpRename
    ) -> Pin<Box<dyn Future<Output = Result<RpRename>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn presign<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 str,
        args: OpPresign
    ) -> Pin<Box<dyn Future<Output = Result<RpPresign>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn batch<'life0, 'async_trait>(
        &'life0 self,
        args: OpBatch
    ) -> Pin<Box<dyn Future<Output = Result<RpBatch>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn blocking_create_dir(
        &self,
        path: &str,
        args: OpCreateDir
    ) -> Result<RpCreateDir> { ... }
    fn blocking_stat(&self, path: &str, args: OpStat) -> Result<RpStat> { ... }
    fn blocking_read(
        &self,
        path: &str,
        args: OpRead
    ) -> Result<(RpRead, Self::BlockingReader)> { ... }
    fn blocking_write(
        &self,
        path: &str,
        args: OpWrite
    ) -> Result<(RpWrite, Self::BlockingWriter)> { ... }
    fn blocking_delete(&self, path: &str, args: OpDelete) -> Result<RpDelete> { ... }
    fn blocking_list(
        &self,
        path: &str,
        args: OpList
    ) -> Result<(RpList, Self::BlockingLister)> { ... }
    fn blocking_copy(
        &self,
        from: &str,
        to: &str,
        args: OpCopy
    ) -> Result<RpCopy> { ... }
    fn blocking_rename(
        &self,
        from: &str,
        to: &str,
        args: OpRename
    ) -> Result<RpRename> { ... }
}

Underlying trait of all backends for implementers.

The actual data access of storage service happens in Accessor layer. Every storage supported by OpenDAL must implement Accessor but not all methods of Accessor will be implemented according to how the storage service is.

For example, user can not modify the content from one HTTP file server directly. So Http implements and provides only read related actions.

Accessor gives default implementation for all methods which will raise ErrorKind::Unsupported error. And what action this Accessor supports will be pointed out in AccessorInfo.

Note

Visit internals for more tutorials.

Operations

• Path in args will all be normalized into the same style, services should handle them based on services’ requirement.
  • Path that ends with / means it’s Dir, otherwise, it’s File.
  • Root dir is /
  • Path will never be empty.
• Operations without capability requirement like metadata, create are basic operations.
  • All services must implement them.
  • Use unimplemented!() if not implemented or can’t implement.
• Operations with capability requirement like presign are optional operations.
  • Services can implement them based on services capabilities.
  • The default implementation should return ErrorKind::Unsupported.

Required Associated Types

type Reader: Read

Reader is the associated reader returned in read operation.

type Writer: Write

Writer is the associated writer returned in write operation.

type Lister: List

Lister is the associated lister returned in list operation.

type BlockingReader: BlockingRead

BlockingReader is the associated reader returned blocking_read operation.

type BlockingWriter: BlockingWrite

BlockingWriter is the associated writer returned blocking_write operation.

type BlockingLister: BlockingList

BlockingLister is the associated lister returned blocking_list operation.

Required Methods

fn info(&self) -> AccessorInfo

Invoke the info operation to get metadata of accessor.

Notes

This function is required to be implemented.

By returning AccessorInfo, underlying services can declare some useful information about it self.

• scheme: declare the scheme of backend.
• capabilities: declare the capabilities of current backend.

Provided Methods

fn create_dir<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpCreateDir ) -> Pin<Box<dyn Future<Output = Result<RpCreateDir>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the create operation on the specified path

Require Capability::create_dir

Behavior

• Input path MUST match with EntryMode, DON’T NEED to check mode.
• Create on existing dir SHOULD succeed.

fn stat<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpStat ) -> Pin<Box<dyn Future<Output = Result<RpStat>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the stat operation on the specified path.

Require Capability::stat

Behavior

• stat empty path means stat backend’s root path.
• stat a path endswith “/” means stating a dir.
• mode and content_length must be set.

fn read<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpRead ) -> Pin<Box<dyn Future<Output = Result<(RpRead, Self::Reader)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the read operation on the specified path, returns a Reader if operate successful.

Require Capability::read

Behavior

• Input path MUST be file path, DON’T NEED to check mode.
• The returning content length may be smaller than the range specified.

fn write<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpWrite ) -> Pin<Box<dyn Future<Output = Result<(RpWrite, Self::Writer)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the write operation on the specified path, returns a written size if operate successful.

Require Capability::write

Behavior

• Input path MUST be file path, DON’T NEED to check mode.

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpDelete ) -> Pin<Box<dyn Future<Output = Result<RpDelete>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the delete operation on the specified path.

Require Capability::delete

Behavior

• delete is an idempotent operation, it’s safe to call Delete on the same path multiple times.
• delete SHOULD return Ok(()) if the path is deleted successfully or not exist.

fn list<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpList ) -> Pin<Box<dyn Future<Output = Result<(RpList, Self::Lister)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the list operation on the specified path.

Require Capability::list

Behavior

• Input path MUST be dir path, DON’T NEED to check mode.
• List non-exist dir should return Empty.

fn copy<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 str, to: &'life2 str, args: OpCopy ) -> Pin<Box<dyn Future<Output = Result<RpCopy>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

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

Require Capability::copy

Behaviour

• from and to MUST be file path, DON’T NEED to check mode.
• Copy on existing file SHOULD succeed.
• Copy on existing file SHOULD overwrite and truncate.

fn rename<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 str, to: &'life2 str, args: OpRename ) -> Pin<Box<dyn Future<Output = Result<RpRename>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

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

Require Capability::rename

fn presign<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpPresign ) -> Pin<Box<dyn Future<Output = Result<RpPresign>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Invoke the presign operation on the specified path.

Require Capability::presign

Behavior

• This API is optional, return std::io::ErrorKind::Unsupported if not supported.

fn batch<'life0, 'async_trait>( &'life0 self, args: OpBatch ) -> Pin<Box<dyn Future<Output = Result<RpBatch>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Invoke the batch operations.

Require Capability::batch

fn blocking_create_dir( &self, path: &str, args: OpCreateDir ) -> Result<RpCreateDir>

Invoke the blocking_create operation on the specified path.

This operation is the blocking version of Accessor::create_dir

Require Capability::create_dir and Capability::blocking

fn blocking_stat(&self, path: &str, args: OpStat) -> Result<RpStat>

Invoke the blocking_stat operation on the specified path.

This operation is the blocking version of Accessor::stat

Require Capability::stat and Capability::blocking

fn blocking_read( &self, path: &str, args: OpRead ) -> Result<(RpRead, Self::BlockingReader)>

Invoke the blocking_read operation on the specified path.

This operation is the blocking version of Accessor::read

Require Capability::read and Capability::blocking

fn blocking_write( &self, path: &str, args: OpWrite ) -> Result<(RpWrite, Self::BlockingWriter)>

Invoke the blocking_write operation on the specified path.

This operation is the blocking version of Accessor::write

Require Capability::write and Capability::blocking

fn blocking_delete(&self, path: &str, args: OpDelete) -> Result<RpDelete>

Invoke the blocking_delete operation on the specified path.

This operation is the blocking version of Accessor::delete

Require Capability::write and Capability::blocking

fn blocking_list( &self, path: &str, args: OpList ) -> Result<(RpList, Self::BlockingLister)>

Invoke the blocking_list operation on the specified path.

This operation is the blocking version of Accessor::list

Require Capability::list and Capability::blocking

Behavior

• List non-exist dir should return Empty.

fn blocking_copy(&self, from: &str, to: &str, args: OpCopy) -> Result<RpCopy>

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

This operation is the blocking version of Accessor::copy

Require Capability::copy and Capability::blocking

fn blocking_rename( &self, from: &str, to: &str, args: OpRename ) -> Result<RpRename>

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

This operation is the blocking version of Accessor::rename

Require Capability::rename and Capability::blocking

Implementations on Foreign Types

impl Accessor for ()

Dummy implementation of accessor.

type Reader = ()

type Writer = ()

type Lister = ()

type BlockingReader = ()

type BlockingWriter = ()

type BlockingLister = ()

fn info(&self) -> AccessorInfo

impl<T: Accessor + ?Sized> Accessor for Arc<T>

All functions in Accessor only requires &self, so it’s safe to implement Accessor for Arc<dyn Accessor>.

type Reader = <T as Accessor>::Reader

type Writer = <T as Accessor>::Writer

type Lister = <T as Accessor>::Lister

type BlockingReader = <T as Accessor>::BlockingReader

type BlockingWriter = <T as Accessor>::BlockingWriter

type BlockingLister = <T as Accessor>::BlockingLister

fn info(&self) -> AccessorInfo

fn create_dir<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpCreateDir ) -> Pin<Box<dyn Future<Output = Result<RpCreateDir>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn stat<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpStat ) -> Pin<Box<dyn Future<Output = Result<RpStat>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn read<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpRead ) -> Pin<Box<dyn Future<Output = Result<(RpRead, Self::Reader)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn write<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpWrite ) -> Pin<Box<dyn Future<Output = Result<(RpWrite, Self::Writer)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpDelete ) -> Pin<Box<dyn Future<Output = Result<RpDelete>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn list<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpList ) -> Pin<Box<dyn Future<Output = Result<(RpList, Self::Lister)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn copy<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 str, to: &'life2 str, args: OpCopy ) -> Pin<Box<dyn Future<Output = Result<RpCopy>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn rename<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 str, to: &'life2 str, args: OpRename ) -> Pin<Box<dyn Future<Output = Result<RpRename>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn presign<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, args: OpPresign ) -> Pin<Box<dyn Future<Output = Result<RpPresign>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn batch<'life0, 'async_trait>( &'life0 self, args: OpBatch ) -> Pin<Box<dyn Future<Output = Result<RpBatch>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn blocking_create_dir( &self, path: &str, args: OpCreateDir ) -> Result<RpCreateDir>

fn blocking_stat(&self, path: &str, args: OpStat) -> Result<RpStat>

fn blocking_read( &self, path: &str, args: OpRead ) -> Result<(RpRead, Self::BlockingReader)>

fn blocking_write( &self, path: &str, args: OpWrite ) -> Result<(RpWrite, Self::BlockingWriter)>

fn blocking_delete(&self, path: &str, args: OpDelete) -> Result<RpDelete>

fn blocking_list( &self, path: &str, args: OpList ) -> Result<(RpList, Self::BlockingLister)>

fn blocking_copy(&self, from: &str, to: &str, args: OpCopy) -> Result<RpCopy>

fn blocking_rename( &self, from: &str, to: &str, args: OpRename ) -> Result<RpRename>

Implementors

impl<L: LayeredAccessor> Accessor for L

type Reader = <L as LayeredAccessor>::Reader

type BlockingReader = <L as LayeredAccessor>::BlockingReader

type Writer = <L as LayeredAccessor>::Writer

type BlockingWriter = <L as LayeredAccessor>::BlockingWriter

type Lister = <L as LayeredAccessor>::Lister

type BlockingLister = <L as LayeredAccessor>::BlockingLister

impl<S: Adapter> Accessor for opendal::raw::adapters::kv::Backend<S>

type Reader = Buffer

type BlockingReader = Buffer

type Writer = KvWriter<S>

type BlockingWriter = KvWriter<S>

type Lister = HierarchyLister<KvLister>

type BlockingLister = HierarchyLister<KvLister>

impl<S: Adapter> Accessor for opendal::raw::adapters::typed_kv::Backend<S>

type Reader = Buffer

type BlockingReader = Buffer

type Writer = KvWriter<S>

type BlockingWriter = KvWriter<S>

type Lister = HierarchyLister<KvLister>

type BlockingLister = HierarchyLister<KvLister>