{"id":21434195,"url":"https://github.com/sdleffler/rad-rs","last_synced_at":"2025-07-14T14:31:22.217Z","repository":{"id":49461252,"uuid":"93903567","full_name":"sdleffler/rad-rs","owner":"sdleffler","description":"Safe, high-level RADOS bindings using the ceph-rust bindings.","archived":false,"fork":false,"pushed_at":"2021-06-17T04:20:29.000Z","size":11065,"stargazers_count":6,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-28T16:56:57.782Z","etag":null,"topics":["ceph","concurrency","rados","rust","storage"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sdleffler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-09T23:18:13.000Z","updated_at":"2024-07-07T14:48:25.000Z","dependencies_parsed_at":"2022-08-26T15:41:30.182Z","dependency_job_id":null,"html_url":"https://github.com/sdleffler/rad-rs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdleffler%2Frad-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdleffler%2Frad-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdleffler%2Frad-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdleffler%2Frad-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdleffler","download_url":"https://codeload.github.com/sdleffler/rad-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225980897,"owners_count":17554919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ceph","concurrency","rados","rust","storage"],"created_at":"2024-11-22T23:33:53.055Z","updated_at":"2024-11-22T23:33:53.495Z","avatar_url":"https://github.com/sdleffler.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/sdleffler/rad-rs.svg?branch=master)](https://travis-ci.org/sdleffler/rad-rs)\n[![Docs Status](https://docs.rs/rad/badge.svg)](https://docs.rs/rad)\n[![On crates.io](https://img.shields.io/crates/v/rad.svg)](https://crates.io/crates/rad)\n\n# rad: High-level Rust library for interfacing with RADOS\n\nThis library provides a typesafe and extremely high-level Rust interface to\nRADOS, the Reliable Autonomous Distributed Object Store. It uses the raw C\nbindings from `ceph-rust`.\n\n# Installation\n\nTo build and use this library, a working installation of the Ceph librados\ndevelopment files is required. On systems with apt-get, this can be acquired\nlike so:\n\n```bash\nwget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo apt-key add -\nsudo apt-add-repository 'deb https://download.ceph.com/debian-luminous/ `lsb_release -sc` main'\nsudo apt-get update\nsudo apt-get install librados-dev\n```\n\n*N.B. `luminous` is the current Ceph release. This library will not work\ncorrectly or as expected with earlier releases of Ceph/librados (Jewel or\nearlier; Kraken is fine.)*\n\nFor more information on installing Ceph packages, see [the Ceph documentation](http://docs.ceph.com/docs/master/install/get-packages/).\n\n# Examples\n\n## Connecting to a cluster\n\nThe following shows how to connect to a RADOS cluster, by providing a path to a\n`ceph.conf` file, a path to the `client.admin` keyring, and requesting to\nconnect with the `admin` user. This API bares little resemblance to the\nbare-metal librados API, but it *is* easy to trace what's happening under the\nhood: `ConnectionBuilder::with_user` or `ConnectionBuilder::new`\nallocates a new `rados_t`. `read_conf_file` calls `rados_conf_read_file`,\n`conf_set` calls `rados_conf_set`, and `connect` calls `rados_connect`.\n\n```rust\nuse rad::ConnectionBuilder;\n\nlet cluster = ConnectionBuilder::with_user(\"admin\").unwrap()\n    .read_conf_file(\"/etc/ceph.conf\").unwrap()\n    .conf_set(\"keyring\", \"/etc/ceph.client.admin.keyring\").unwrap()\n    .connect()?;\n```\n\nThe type returned from `.connect()` is a `Cluster` handle, which is a wrapper around a `rados_t` which guarantees a `rados_shutdown` on the connection when dropped.\n\n## Writing a file to a cluster with synchronous I/O\n\n```rust\nuse std::fs::File;\nuse std::io::Read;\n\nuse rad::ConnectionBuilder;\n\nlet cluster = ConnectionBuilder::with_user(\"admin\")?\n    .read_conf_file(\"/etc/ceph.conf\")?\n    .conf_set(\"keyring\", \"/etc/ceph.client.admin.keyring\")?\n    .connect()?;\n\n// Read in bytes from some file to send to the cluster.\nlet file = File::open(\"/path/to/file\")?;\nlet mut bytes = Vec::new();\nfile.read_to_end(\u0026mut bytes)?;\n\nlet pool = cluster.get_pool_context(\"rbd\")?;\n\npool.write_full(\"object-name\", \u0026bytes)?;\n\n// Our file is now in the cluster! We can check for its existence:\nassert!(pool.exists(\"object-name\")?);\n\n// And we can also check that it contains the bytes we wrote to it.\nlet mut bytes_from_cluster = vec![0u8; bytes.len()];\nlet bytes_read = pool.read(\"object-name\", \u0026mut bytes_from_cluster, 0)?;\nassert_eq!(bytes_read, bytes_from_cluster.len());\nassert!(bytes_from_cluster == bytes);\n```\n\n## Writing multiple objects to a cluster with asynchronous I/O and `futures-rs`\n\n`rad-rs` also supports the librados AIO interface, using the `futures` crate.\nThis example will start `NUM_OBJECTS` writes concurrently and then wait for\nthem all to finish.\n\n```rust\nuse std::fs::File;\nuse std::io::Read;\n\nuse rand::{Rng, SeedableRng, XorShiftRng};\n\nuse rad::ConnectionBuilder;\n\nconst NUM_OBJECTS: usize = 8;\n\nlet cluster = ConnectionBuilder::with_user(\"admin\")?\n    .read_conf_file(\"/etc/ceph.conf\")?\n    .conf_set(\"keyring\", \"/etc/ceph.client.admin.keyring\")?\n    .connect()?;\n\nlet pool = cluster.get_pool_context(\"rbd\")?;\n\nstream::iter_ok((0..NUM_OBJECTS)\n    .map(|i| {\n        let bytes = XorShiftRng::from_seed([i as u32 + 1, 2, 3, 4])\n            .gen_iter::\u003cu8\u003e()\n            .take(1 \u003c\u003c 16).collect();\n\n        let name = format!(\"object-{}\", i);\n\n        pool.write_full_async(name, \u0026bytes)\n    }))\n    .buffer_unordered(NUM_OBJECTS)\n    .collect()\n    .wait()?;\n```\n\n# Running tests\n\nIntegration tests against a demo cluster are provided, and the test suite\n(which is admittedly a little bare at the moment) uses Docker and a container\nderived from the Ceph `ceph/demo` container to bring a small Ceph cluster\nonline, locally. A script is provided for launching the test suite:\n\n```sh\n./tests/run-all-tests.sh\n```\n\nLaunching the test suite requires Docker to be installed.\n\n# License\n\nThis project is licensed under the [Mozilla Public License, version 2.0.](https://www.mozilla.org/en-US/MPL/2.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdleffler%2Frad-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdleffler%2Frad-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdleffler%2Frad-rs/lists"}