goosefs_sdk/lib.rs
1//! Goosefs Rust gRPC Client
2//!
3//! A Rust client library that communicates with Goosefs Master/Worker
4//! via gRPC (tonic/protobuf). This is the **Layer 3** crate in the
5//! Lance → OpenDAL → Goosefs architecture.
6//!
7//! # Architecture
8//!
9//! ```text
10//! ┌─────────────────────────────────────────────────────┐
11//! │ ★ High-Level API (recommended) │
12//! │ GoosefsFileWriter — end-to-end file write pipeline │
13//! │ GoosefsFileReader — end-to-end file read pipeline │
14//! ├─────────────────────────────────────────────────────┤
15//! │ MasterClient — File metadata CRUD (Master:9200) │
16//! │ WorkerMgrClient — Worker discovery (Master:9200) │
17//! │ VersionClient — Service handshake (Master:9200) │
18//! │ WorkerClient — Block streaming (Worker:9203) │
19//! ├─────────────────────────────────────────────────────┤
20//! │ BlockMapper — file range → block read plans │
21//! │ WorkerRouter — consistent hash block→worker │
22//! ├─────────────────────────────────────────────────────┤
23//! │ GrpcBlockReader — bidirectional streaming read │
24//! │ GrpcBlockWriter — bidirectional streaming write │
25//! └─────────────────────────────────────────────────────┘
26//! ```
27//!
28//! # Quick Start — High-Level API
29//!
30//! ```rust,no_run
31//! use std::sync::Arc;
32//! use goosefs_sdk::context::FileSystemContext;
33//! use goosefs_sdk::io::{GoosefsFileWriter, GoosefsFileReader};
34//! use goosefs_sdk::config::GoosefsConfig;
35//!
36//! #[tokio::main]
37//! async fn main() -> goosefs_sdk::error::Result<()> {
38//! // Build once — the only call that performs TCP+SASL.
39//! let ctx = FileSystemContext::connect(GoosefsConfig::new("127.0.0.1:9200")).await?;
40//!
41//! // Write a file (zero new connections — reuses ctx).
42//! GoosefsFileWriter::write_file_with_context(ctx.clone(), "/my-file.txt", b"Hello!").await?;
43//!
44//! // Read it back.
45//! let data = GoosefsFileReader::read_file_with_context(ctx.clone(), "/my-file.txt").await?;
46//! println!("read {} bytes", data.len());
47//!
48//! Ok(())
49//! }
50//! ```
51//!
52//! # Low-Level API
53//!
54//! ```rust,no_run
55//! use goosefs_sdk::client::MasterClient;
56//! use goosefs_sdk::config::GoosefsConfig;
57//!
58//! #[tokio::main]
59//! async fn main() -> goosefs_sdk::error::Result<()> {
60//! let config = GoosefsConfig::default();
61//! let master = MasterClient::connect(&config).await?;
62//! let file_info = master.get_status("/my-file.txt").await?;
63//! println!("file length: {:?}", file_info.length);
64//! Ok(())
65//! }
66//! ```
67
68pub mod auth;
69pub mod block;
70pub mod client;
71pub mod config;
72pub mod context;
73pub mod error;
74pub mod fs;
75pub mod io;
76pub mod retry;
77
78// Re-export commonly used types for convenience.
79pub use crate::config::{ConfigRefresher, TransparentAccelerationSwitch, WriteType};
80pub use crate::config::{
81 ENV_AUTHORIZATION_PERMISSION_ENABLED, ENV_AUTH_TYPE, ENV_AUTH_USERNAME, ENV_BLOCK_SIZE,
82 ENV_CHUNK_SIZE, ENV_CONFIG_MANAGER_RPC_ADDRESSES, ENV_CONFIG_RPC_PORT,
83 ENV_LOGIN_IMPERSONATION_USERNAME, ENV_MASTER_ADDR,
84 ENV_TRANSPARENT_ACCELERATION_COSRANGER_ENABLED, ENV_TRANSPARENT_ACCELERATION_ENABLED,
85 ENV_WRITE_TYPE, IMPERSONATION_NONE, STORAGE_OPT_AUTHORIZATION_PERMISSION_ENABLED,
86 STORAGE_OPT_AUTH_TYPE, STORAGE_OPT_AUTH_USERNAME, STORAGE_OPT_BLOCK_SIZE,
87 STORAGE_OPT_CHUNK_SIZE, STORAGE_OPT_CONFIG_MANAGER_RPC_ADDRESSES, STORAGE_OPT_CONFIG_RPC_PORT,
88 STORAGE_OPT_LOGIN_IMPERSONATION_USERNAME, STORAGE_OPT_MASTER_ADDR,
89 STORAGE_OPT_TRANSPARENT_ACCELERATION_COSRANGER_ENABLED,
90 STORAGE_OPT_TRANSPARENT_ACCELERATION_ENABLED, STORAGE_OPT_WRITE_TYPE,
91};
92pub use crate::context::FileSystemContext;
93pub use crate::proto::grpc::file::WritePType;
94
95/// Generated protobuf / gRPC types from Goosefs `.proto` definitions.
96///
97/// The module layout must mirror the proto package hierarchy exactly so that
98/// prost-generated `super::` relative paths resolve correctly:
99///
100/// ```text
101/// proto (root)
102/// ├── grpc — com.qcloud.cos.goosefs.grpc (WorkerNetAddress, BlockInfo …)
103/// │ ├── file — com.qcloud.cos.goosefs.grpc.file (FileSystemMasterClientService)
104/// │ ├── block — com.qcloud.cos.goosefs.grpc.block (BlockWorker, WorkerManagerMaster…)
105/// │ ├── version — com.qcloud.cos.goosefs.grpc.version (ServiceVersionClientService)
106/// │ └── fscommon — com.qcloud.cos.goosefs.grpc.fscommon (LoadDescendantPType)
107/// └── proto — (intermediate)
108/// ├── dataserver — com.qcloud.cos.goosefs.proto.dataserver
109/// ├── security — com.qcloud.cos.goosefs.proto.security (Capability, DelegationToken)
110/// ├── shared — com.qcloud.cos.goosefs.proto.shared (AccessControlList)
111/// └── status — com.qcloud.cos.goosefs.proto.status (PStatus)
112/// ```
113///
114/// Key path resolutions from generated code:
115/// - `grpc::file` uses `super::Bits` → `grpc::Bits` ✓
116/// - `grpc::file` uses `super::super::proto::security::Capability`
117/// → `proto(root)::proto::security::Capability` ✓
118/// - `proto::dataserver` uses `super::shared::*` → `proto(inner)::shared::*` ✓
119pub mod proto {
120 pub mod grpc {
121 include!("generated/com.qcloud.cos.goosefs.grpc.rs");
122
123 pub mod file {
124 include!("generated/com.qcloud.cos.goosefs.grpc.file.rs");
125 }
126
127 pub mod block {
128 include!("generated/com.qcloud.cos.goosefs.grpc.block.rs");
129 }
130
131 pub mod version {
132 include!("generated/com.qcloud.cos.goosefs.grpc.version.rs");
133 }
134
135 pub mod fscommon {
136 include!("generated/com.qcloud.cos.goosefs.grpc.fscommon.rs");
137 }
138
139 pub mod sasl {
140 include!("generated/com.qcloud.cos.goosefs.grpc.sasl.rs");
141 }
142 }
143
144 pub mod proto {
145 pub mod dataserver {
146 include!("generated/com.qcloud.cos.goosefs.proto.dataserver.rs");
147 }
148
149 pub mod security {
150 include!("generated/com.qcloud.cos.goosefs.proto.security.rs");
151 }
152
153 pub mod shared {
154 include!("generated/com.qcloud.cos.goosefs.proto.shared.rs");
155 }
156
157 pub mod status {
158 include!("generated/com.qcloud.cos.goosefs.proto.status.rs");
159 }
160 }
161}