google_cloud_storage/storage/
stub.rs

1// Copyright 2025 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use crate::Result;
16use crate::model::{Object, ReadObjectRequest};
17use crate::model_ext::WriteObjectRequest;
18use crate::read_object::ReadObjectResponse;
19use crate::storage::request_options::RequestOptions;
20use crate::streaming_source::{Seek, StreamingSource};
21use crate::{
22    http::HeaderMap,
23    model_ext::{OpenObjectRequest, ReadRange},
24    object_descriptor::ObjectDescriptor as Descriptor,
25};
26#[cfg(google_cloud_unstable_storage_bidi)]
27use bytes::Bytes;
28use gaxi::unimplemented::UNIMPLEMENTED;
29
30/// Defines the trait used to implement [crate::client::Storage].
31///
32/// Application developers may need to implement this trait to mock
33/// `client::Storage`. In other use-cases, application developers only
34/// use `client::Storage` and need not be concerned with this trait or
35/// its implementations.
36///
37/// Services gain new RPCs routinely. Consequently, this trait gains new methods
38/// too. To avoid breaking applications the trait provides a default
39/// implementation of each method. Most of these implementations just return an
40/// error.
41pub trait Storage: std::fmt::Debug + Send + Sync {
42    /// Implements [crate::client::Storage::read_object].
43    fn read_object(
44        &self,
45        _req: ReadObjectRequest,
46        _options: RequestOptions,
47    ) -> impl std::future::Future<Output = Result<ReadObjectResponse>> + Send {
48        unimplemented_stub::<ReadObjectResponse>()
49    }
50
51    /// Implements [crate::client::Storage::write_object].
52    fn write_object_buffered<P>(
53        &self,
54        _payload: P,
55        _req: WriteObjectRequest,
56        _options: RequestOptions,
57    ) -> impl std::future::Future<Output = Result<Object>> + Send
58    where
59        P: StreamingSource + Send + Sync + 'static,
60    {
61        unimplemented_stub::<Object>()
62    }
63
64    /// Implements [crate::client::Storage::write_object].
65    fn write_object_unbuffered<P>(
66        &self,
67        _payload: P,
68        _req: WriteObjectRequest,
69        _options: RequestOptions,
70    ) -> impl std::future::Future<Output = Result<Object>> + Send
71    where
72        P: StreamingSource + Seek + Send + Sync + 'static,
73    {
74        unimplemented_stub::<Object>()
75    }
76
77    /// Implements [crate::client::Storage::open_object].
78    fn open_object(
79        &self,
80        _request: OpenObjectRequest,
81        _options: RequestOptions,
82    ) -> impl std::future::Future<Output = Result<(Descriptor, Vec<ReadObjectResponse>)>> + Send
83    {
84        unimplemented_stub::<(Descriptor, Vec<ReadObjectResponse>)>()
85    }
86
87    #[cfg(google_cloud_unstable_storage_bidi)]
88    /// Implements [crate::client::Storage::open_appendable_object].
89    fn open_appendable_object(
90        &self,
91        _request: crate::model_ext::OpenAppendableObjectRequest,
92        _options: RequestOptions,
93    ) -> impl std::future::Future<
94        Output = Result<crate::appendable_object_writer::AppendableObjectWriter>,
95    > + Send {
96        unimplemented_stub::<crate::appendable_object_writer::AppendableObjectWriter>()
97    }
98
99    #[cfg(google_cloud_unstable_storage_bidi)]
100    /// Implements [crate::client::Storage::reopen_appendable_object].
101    fn reopen_appendable_object(
102        &self,
103        _request: crate::model_ext::ReopenAppendableObjectRequest,
104        _options: RequestOptions,
105    ) -> impl std::future::Future<
106        Output = Result<crate::appendable_object_writer::AppendableObjectWriter>,
107    > + Send {
108        unimplemented_stub::<crate::appendable_object_writer::AppendableObjectWriter>()
109    }
110}
111
112/// Defines the trait used to implement [crate::object_descriptor::ObjectDescriptor].
113///
114/// Application developers may need to implement this trait to mock
115/// `ObjectDescriptor`. In other use-cases, application developers
116/// should use `ObjectDescriptor` directly, and need not be concerned
117/// with this trait or its implementations.
118pub trait ObjectDescriptor: std::fmt::Debug + Send + Sync {
119    /// The implementation for [ObjectDescriptor::object][Descriptor::object].
120    fn object(&self) -> Object;
121
122    /// The implementation for [ObjectDescriptor::read_range][Descriptor::read_range].
123    fn read_range(&self, range: ReadRange) -> impl Future<Output = ReadObjectResponse> + Send;
124
125    /// The implementation for [ObjectDescriptor::headers][Descriptor::headers].
126    fn headers(&self) -> HeaderMap;
127}
128
129/// Defines the trait used to implement [crate::appendable_object_writer::AppendableObjectWriter].
130///
131/// Application developers may need to implement this trait to mock
132/// `AppendableObjectWriter`. In other use-cases, application developers
133/// should use `AppendableObjectWriter` directly, and need not be concerned
134/// with this trait or its implementations.
135#[cfg(google_cloud_unstable_storage_bidi)]
136#[cfg_attr(docsrs, doc(cfg(feature = "unstable-stream")))]
137pub trait AppendableObjectWriter: std::fmt::Debug + Send + Sync {
138    /// The implementation for [AppendableObjectWriter::append][crate::appendable_object_writer::AppendableObjectWriter::append].
139    fn append(
140        &mut self,
141        chunk: Bytes,
142    ) -> impl std::future::Future<Output = crate::Result<()>> + Send;
143
144    /// The implementation for [AppendableObjectWriter::flush][crate::appendable_object_writer::AppendableObjectWriter::flush].
145    fn flush(&mut self) -> impl std::future::Future<Output = crate::Result<i64>> + Send;
146
147    /// The implementation for [AppendableObjectWriter::finalize][crate::appendable_object_writer::AppendableObjectWriter::finalize].
148    fn finalize(
149        self,
150    ) -> impl std::future::Future<Output = crate::Result<crate::model::Object>> + Send;
151
152    /// The implementation for [AppendableObjectWriter::close][crate::appendable_object_writer::AppendableObjectWriter::close].
153    fn close(self) -> impl std::future::Future<Output = crate::Result<i64>> + Send;
154
155    /// The implementation for [AppendableObjectWriter::generation][crate::appendable_object_writer::AppendableObjectWriter::generation].
156    fn generation(&self) -> i64;
157
158    /// The implementation for [AppendableObjectWriter::persisted_size][crate::appendable_object_writer::AppendableObjectWriter::persisted_size].
159    fn persisted_size(&self) -> i64;
160}
161
162async fn unimplemented_stub<T>() -> google_cloud_gax::Result<T> {
163    unimplemented!("{UNIMPLEMENTED}");
164}
google_cloud_storage/storage/stub.rs

google_cloud_storage/storage/
stub.rs
