Trait Access

pub trait Access:
    Send
    + Sync
    + Debug
    + Unpin
    + 'static {
    type Reader: Read;
    type Writer: Write;
    type Lister: List;
    type Deleter: Delete;

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

    // Provided methods
    fn create_dir(
        &self,
        path: &str,
        args: OpCreateDir,
    ) -> impl Future<Output = Result<RpCreateDir, Error>> + MaybeSend { ... }
    fn stat(
        &self,
        path: &str,
        args: OpStat,
    ) -> impl Future<Output = Result<RpStat, Error>> + MaybeSend { ... }
    fn read(
        &self,
        path: &str,
        args: OpRead,
    ) -> impl Future<Output = Result<(RpRead, Self::Reader), Error>> + MaybeSend { ... }
    fn write(
        &self,
        path: &str,
        args: OpWrite,
    ) -> impl Future<Output = Result<(RpWrite, Self::Writer), Error>> + MaybeSend { ... }
    fn delete(
        &self,
    ) -> impl Future<Output = Result<(RpDelete, Self::Deleter), Error>> + MaybeSend { ... }
    fn list(
        &self,
        path: &str,
        args: OpList,
    ) -> impl Future<Output = Result<(RpList, Self::Lister), Error>> + MaybeSend { ... }
    fn copy(
        &self,
        from: &str,
        to: &str,
        args: OpCopy,
    ) -> impl Future<Output = Result<RpCopy, Error>> + MaybeSend { ... }
    fn rename(
        &self,
        from: &str,
        to: &str,
        args: OpRename,
    ) -> impl Future<Output = Result<RpRename, Error>> + MaybeSend { ... }
    fn presign(
        &self,
        path: &str,
        args: OpPresign,
    ) -> impl Future<Output = Result<RpPresign, Error>> + MaybeSend { ... }
}

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 Access but not all methods of Access 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.

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

Note

Visit [internals][crate::docs::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 Deleter: Delete

Deleter is the associated deleter returned in delete operation.

Required Methods

fn info(&self) -> Arc<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 itself.

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

Provided Methods

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

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( &self, path: &str, args: OpStat, ) -> impl Future<Output = Result<RpStat, Error>> + MaybeSend

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( &self, path: &str, args: OpRead, ) -> impl Future<Output = Result<(RpRead, Self::Reader), Error>> + MaybeSend

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( &self, path: &str, args: OpWrite, ) -> impl Future<Output = Result<(RpWrite, Self::Writer), Error>> + MaybeSend

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( &self, ) -> impl Future<Output = Result<(RpDelete, Self::Deleter), Error>> + MaybeSend

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( &self, path: &str, args: OpList, ) -> impl Future<Output = Result<(RpList, Self::Lister), Error>> + MaybeSend

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( &self, from: &str, to: &str, args: OpCopy, ) -> impl Future<Output = Result<RpCopy, Error>> + MaybeSend

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( &self, 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.

Require [Capability::rename]

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

Invoke the presign operation on the specified path.

Require [Capability::presign]

Behavior

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

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 Access for ()

Dummy implementation of accessor.

type Reader = ()

type Writer = ()

type Lister = ()

type Deleter = ()

fn info(&self) -> Arc<AccessorInfo>

impl<T> Access for Arc<T>

where T: Access + ?Sized,

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

type Reader = <T as Access>::Reader

type Writer = <T as Access>::Writer

type Lister = <T as Access>::Lister

type Deleter = <T as Access>::Deleter

fn info(&self) -> Arc<AccessorInfo>

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

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

fn read( &self, path: &str, args: OpRead, ) -> impl Future<Output = Result<(RpRead, <Arc<T> as Access>::Reader), Error>> + MaybeSend

fn write( &self, path: &str, args: OpWrite, ) -> impl Future<Output = Result<(RpWrite, <Arc<T> as Access>::Writer), Error>> + MaybeSend

fn delete( &self, ) -> impl Future<Output = Result<(RpDelete, <Arc<T> as Access>::Deleter), Error>> + MaybeSend

fn list( &self, path: &str, args: OpList, ) -> impl Future<Output = Result<(RpList, <Arc<T> as Access>::Lister), Error>> + MaybeSend

fn copy( &self, from: &str, to: &str, args: OpCopy, ) -> impl Future<Output = Result<RpCopy, Error>> + MaybeSend

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

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

Implementors

impl Access for dyn AccessDyn

type Reader = Box<dyn ReadDyn>

type Writer = Box<dyn WriteDyn>

type Deleter = Box<dyn DeleteDyn>

type Lister = Box<dyn ListDyn>

impl<L> Access for L

where L: LayeredAccess,

type Reader = <L as LayeredAccess>::Reader

type Writer = <L as LayeredAccess>::Writer

type Lister = <L as LayeredAccess>::Lister

type Deleter = <L as LayeredAccess>::Deleter

impl<S> Access for Backend<S>

where S: Adapter,

type Reader = Buffer

type Writer = KvWriter<S>

type Lister = HierarchyLister<KvLister<<S as Adapter>::Scanner>>

type Deleter = OneShotDeleter<KvDeleter<S>>

impl<S> Access for Backend<S>

where S: Adapter,

type Reader = Buffer

type Writer = KvWriter<S>

type Lister = HierarchyLister<KvLister>

type Deleter = OneShotDeleter<KvDeleter<S>>