Crate goosefs_sdk 

Goosefs Rust gRPC Client

A Rust client library that communicates with Goosefs Master/Worker via gRPC (tonic/protobuf). This is the Layer 3 crate in the Lance → OpenDAL → Goosefs architecture.

Architecture

┌─────────────────────────────────────────────────────┐
│  ★ High-Level API (recommended)                     │
│  GoosefsFileWriter — end-to-end file write pipeline │
│  GoosefsFileReader — end-to-end file read pipeline  │
├─────────────────────────────────────────────────────┤
│  MasterClient    — File metadata CRUD (Master:9200) │
│  WorkerMgrClient — Worker discovery  (Master:9200)  │
│  VersionClient   — Service handshake (Master:9200)  │
│  WorkerClient    — Block streaming   (Worker:9203)  │
├─────────────────────────────────────────────────────┤
│  BlockMapper     — file range → block read plans    │
│  WorkerRouter    — consistent hash block→worker     │
├─────────────────────────────────────────────────────┤
│  GrpcBlockReader — bidirectional streaming read     │
│  GrpcBlockWriter — bidirectional streaming write    │
└─────────────────────────────────────────────────────┘

Quick Start — High-Level API

use std::sync::Arc;
use goosefs_sdk::context::FileSystemContext;
use goosefs_sdk::io::{GoosefsFileWriter, GoosefsFileReader};
use goosefs_sdk::config::GoosefsConfig;

#[tokio::main]
async fn main() -> goosefs_sdk::error::Result<()> {
    // Build once — the only call that performs TCP+SASL.
    let ctx = FileSystemContext::connect(GoosefsConfig::new("127.0.0.1:9200")).await?;

    // Write a file (zero new connections — reuses ctx).
    GoosefsFileWriter::write_file_with_context(ctx.clone(), "/my-file.txt", b"Hello!").await?;

    // Read it back.
    let data = GoosefsFileReader::read_file_with_context(ctx.clone(), "/my-file.txt").await?;
    println!("read {} bytes", data.len());

    Ok(())
}

Low-Level API

use goosefs_sdk::client::MasterClient;
use goosefs_sdk::config::GoosefsConfig;

#[tokio::main]
async fn main() -> goosefs_sdk::error::Result<()> {
    let config = GoosefsConfig::default();
    let master = MasterClient::connect(&config).await?;
    let file_info = master.get_status("/my-file.txt").await?;
    println!("file length: {:?}", file_info.length);
    Ok(())
}

Re-exports

pub use crate::config::ConfigRefresher;

pub use crate::config::TransparentAccelerationSwitch;

pub use crate::config::WriteType;

pub use crate::config::ENV_APP_ID;

pub use crate::config::ENV_AUTHORIZATION_PERMISSION_ENABLED;

pub use crate::config::ENV_AUTH_TYPE;

pub use crate::config::ENV_AUTH_USERNAME;

pub use crate::config::ENV_BLOCK_SIZE;

pub use crate::config::ENV_CHUNK_SIZE;

pub use crate::config::ENV_CONFIG_MANAGER_RPC_ADDRESSES;

pub use crate::config::ENV_CONFIG_RPC_PORT;

pub use crate::config::ENV_FILE_INFO_CACHE_CAPACITY;

pub use crate::config::ENV_FILE_INFO_CACHE_TTL_MS;

pub use crate::config::ENV_LOGIN_IMPERSONATION_USERNAME;

pub use crate::config::ENV_MASTER_ADDR;

pub use crate::config::ENV_METRICS_ENABLED;

pub use crate::config::ENV_METRICS_HEARTBEAT_INTERVAL_MS;

pub use crate::config::ENV_PUSHGATEWAY_ENABLED;

pub use crate::config::ENV_PUSHGATEWAY_ENDPOINT;

pub use crate::config::ENV_PUSHGATEWAY_INSTANCE;

pub use crate::config::ENV_PUSHGATEWAY_JOB;

pub use crate::config::ENV_PUSHGATEWAY_PUSH_INTERVAL_MS;

pub use crate::config::ENV_SHORT_CIRCUIT_ADVISE;

pub use crate::config::ENV_SHORT_CIRCUIT_CACHE_CAPACITY;

pub use crate::config::ENV_SHORT_CIRCUIT_CACHE_TTL_MS;

pub use crate::config::ENV_SHORT_CIRCUIT_ENABLED;

pub use crate::config::ENV_SHORT_CIRCUIT_MIN_BLOCK_SIZE;

pub use crate::config::ENV_SHORT_CIRCUIT_NEG_CACHE_TTL_MS;

pub use crate::config::ENV_SHORT_CIRCUIT_PREFETCH_COALESCE_GAP;

pub use crate::config::ENV_SHORT_CIRCUIT_PREFETCH_ENABLED;

pub use crate::config::ENV_SHORT_CIRCUIT_PREFETCH_MAX_BATCH;

pub use crate::config::ENV_SHORT_CIRCUIT_SIGBUS_HANDLER;

pub use crate::config::ENV_SHORT_CIRCUIT_THP;

pub use crate::config::ENV_TRANSPARENT_ACCELERATION_COSRANGER_ENABLED;

pub use crate::config::ENV_TRANSPARENT_ACCELERATION_ENABLED;

pub use crate::config::ENV_WORKER_CONNECTION_POOL_SIZE;

pub use crate::config::ENV_WRITE_TYPE;

pub use crate::config::IMPERSONATION_NONE;

pub use crate::config::STORAGE_OPT_AUTHORIZATION_PERMISSION_ENABLED;

pub use crate::config::STORAGE_OPT_AUTH_TYPE;

pub use crate::config::STORAGE_OPT_AUTH_USERNAME;

pub use crate::config::STORAGE_OPT_BLOCK_SIZE;

pub use crate::config::STORAGE_OPT_CHUNK_SIZE;

pub use crate::config::STORAGE_OPT_CONFIG_MANAGER_RPC_ADDRESSES;

pub use crate::config::STORAGE_OPT_CONFIG_RPC_PORT;

pub use crate::config::STORAGE_OPT_FILE_INFO_CACHE_CAPACITY;

pub use crate::config::STORAGE_OPT_FILE_INFO_CACHE_TTL_MS;

pub use crate::config::STORAGE_OPT_LOGIN_IMPERSONATION_USERNAME;

pub use crate::config::STORAGE_OPT_MASTER_ADDR;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_ADVISE;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_CACHE_CAPACITY;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_CACHE_TTL_MS;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_ENABLED;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_MIN_BLOCK_SIZE;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_NEG_CACHE_TTL_MS;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_PREFETCH_COALESCE_GAP;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_PREFETCH_ENABLED;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_PREFETCH_MAX_BATCH;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_SIGBUS_HANDLER;

pub use crate::config::STORAGE_OPT_SHORT_CIRCUIT_THP;

pub use crate::config::STORAGE_OPT_TRANSPARENT_ACCELERATION_COSRANGER_ENABLED;

pub use crate::config::STORAGE_OPT_TRANSPARENT_ACCELERATION_ENABLED;

pub use crate::config::STORAGE_OPT_WORKER_CONNECTION_POOL_SIZE;

pub use crate::config::STORAGE_OPT_WRITE_TYPE;

pub use crate::context::FileSystemContext;

pub use crate::proto::grpc::file::WritePType;

Modules

auth

Authentication module — Goosefs gRPC channel authentication support.

block

Block mapping and worker routing modules.

cache

Client-side local page cache.

client

gRPC client modules for Goosefs Master and Worker services.

config

Client configuration for Goosefs gRPC connections.

context

FileSystemContext — shared connection pool and routing context.

error

Error types for the Goosefs Rust client.

fs

Goosefs filesystem abstractions.

io

I/O modules: block-level streaming and high-level file read/write over gRPC.

metrics

Client metrics collection and heartbeat infrastructure.

proto

Generated protobuf / gRPC types from Goosefs .proto definitions.

retry

Retry policies for Goosefs client operations.