From 65e5ddf014e0cf94c17280d935871fe335545cf6 Mon Sep 17 00:00:00 2001 From: Maksym Pavlenko Date: Thu, 28 Sep 2023 11:06:20 -0700 Subject: [PATCH] Simplify doc management Signed-off-by: Maksym Pavlenko --- crates/client/Cargo.toml | 4 +++ crates/client/src/lib.rs | 3 +-- crates/logging/Cargo.toml | 8 +++++- crates/logging/src/lib.rs | 9 +------ crates/runc/Cargo.toml | 11 ++++---- crates/runc/src/lib.rs | 2 ++ crates/shim-protos/Cargo.toml | 8 +++++- crates/shim-protos/README.md | 21 +++++++++++++--- crates/shim-protos/src/lib.rs | 47 +---------------------------------- crates/shim/Cargo.toml | 16 ++++++++---- crates/shim/README.md | 19 ++++++++++++-- crates/shim/src/lib.rs | 18 +------------- crates/snapshots/Cargo.toml | 6 +++++ crates/snapshots/src/lib.rs | 36 +-------------------------- 14 files changed, 83 insertions(+), 125 deletions(-) diff --git a/crates/client/Cargo.toml b/crates/client/Cargo.toml index 0e9b6aa2..71bc88a5 100644 --- a/crates/client/Cargo.toml +++ b/crates/client/Cargo.toml @@ -34,9 +34,13 @@ tonic-build.workspace = true [features] connect = ["tokio", "tower"] +docs = [] # Technically Tonic doesn't require Tokio and Tower dependencies here. # However we need them to implement `connect` helper and it's highly unlikely # that Tonic will be used with any other async runtime (see https://github.com/hyperium/tonic/issues/152) # So we enable `connect` feature by default (use `--no-default-features` otherwise). default = ["connect"] + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs index f7a764b6..6f482f45 100644 --- a/crates/client/src/lib.rs +++ b/crates/client/src/lib.rs @@ -14,12 +14,11 @@ limitations under the License. */ +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] // No way to derive Eq with tonic :( // See https://github.com/hyperium/tonic/issues/1056 #![allow(clippy::derive_partial_eq_without_eq)] -//! A GRPC client to query containerd's API. - pub use tonic; /// Generated `containerd.types` types. diff --git a/crates/logging/Cargo.toml b/crates/logging/Cargo.toml index 83011ba7..c59fdcdd 100644 --- a/crates/logging/Cargo.toml +++ b/crates/logging/Cargo.toml @@ -3,7 +3,7 @@ name = "containerd-shim-logging" version = "0.1.1" authors = [ "Maksym Pavlenko ", - "The containerd Authors" + "The containerd Authors", ] description = "Logger extension for containerd v2 runtime" keywords = ["containerd", "shim", "containers"] @@ -13,3 +13,9 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true + +[features] +docs = [] + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/logging/src/lib.rs b/crates/logging/src/lib.rs index 67ebd51a..90fc8c4f 100644 --- a/crates/logging/src/lib.rs +++ b/crates/logging/src/lib.rs @@ -14,14 +14,7 @@ limitations under the License. */ -//! Helper library to implement custom shim loggers for containerd. -//! -//! # Runtime -//! containerd shims may support pluggable logging via stdio URIs. Binary logging has the ability to -//! forward a container's STDIO to an external binary for consumption. -//! -//! This crates replicates APIs provided by Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md#logging). -//! +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] use std::{env, fmt, fs, os::unix::io::FromRawFd, process}; diff --git a/crates/runc/Cargo.toml b/crates/runc/Cargo.toml index f9e80267..a6fa3d50 100644 --- a/crates/runc/Cargo.toml +++ b/crates/runc/Cargo.toml @@ -1,10 +1,7 @@ [package] name = "runc" version = "0.2.0" -authors = [ - "Yuna Tomida ", - "The containerd Authors", -] +authors = ["Yuna Tomida ", "The containerd Authors"] description = "A crate for consuming the runc binary in your Rust applications" keywords = ["containerd", "containers", "runc"] categories = ["api-bindings", "asynchronous"] @@ -16,6 +13,7 @@ homepage.workspace = true [features] async = ["tokio", "async-trait", "futures", "tokio-pipe"] +docs = [] [dependencies] libc.workspace = true @@ -36,4 +34,7 @@ uuid.workspace = true async-trait = { workspace = true, optional = true } futures = { workspace = true, optional = true } tokio = { workspace = true, features = ["full"], optional = true } -tokio-pipe = { version="0.2.10", optional = true } +tokio-pipe = { version = "0.2.10", optional = true } + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/runc/src/lib.rs b/crates/runc/src/lib.rs index d222dc1b..ccae60ef 100644 --- a/crates/runc/src/lib.rs +++ b/crates/runc/src/lib.rs @@ -33,6 +33,8 @@ * limitations under the License. */ +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] + //! A crate for consuming the runc binary in your Rust applications, similar to //! [go-runc](https://github.com/containerd/go-runc) for Go. use std::{ diff --git a/crates/shim-protos/Cargo.toml b/crates/shim-protos/Cargo.toml index eebcbf33..94cd7d43 100644 --- a/crates/shim-protos/Cargo.toml +++ b/crates/shim-protos/Cargo.toml @@ -18,6 +18,7 @@ homepage.workspace = true default = [] async = ["ttrpc/async", "async-trait"] sandbox = [] +docs = [] [[example]] name = "shim-proto-server" @@ -61,5 +62,10 @@ ttrpc-codegen = "0.4" [dev-dependencies] ctrlc = { version = "3.0", features = ["termination"] } log.workspace = true -simple_logger = { version = "4.0", default-features = false, features = ["stderr"]} +simple_logger = { version = "4.0", default-features = false, features = [ + "stderr", +] } tokio = { workspace = true, features = ["full"] } + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/shim-protos/README.md b/crates/shim-protos/README.md index 1bb9cb9a..62fd37f2 100644 --- a/crates/shim-protos/README.md +++ b/crates/shim-protos/README.md @@ -5,13 +5,28 @@ [![Crates.io](https://img.shields.io/crates/l/containerd-shim-protos)](https://github.com/containerd/rust-extensions/blob/main/LICENSE) [![CI](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/containerd/rust-extensions/actions/workflows/ci.yml) -TTRPC bindings for containerd's shim events and interfaces. +`containerd-shim-protos` contains TTRPC bindings and client/server code to interact with containerd's runtime v2 shims. -## Design +## Runtime +This crate is mainly expected to be useful to interact with containerd's shim runtime. +Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd. +The shim API is minimal and scoped to the execution lifecycle of a container. + +To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md). +## Design The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the -[Containerd shim v2](https://github.com/containerd/containerd/blob/main/api/runtime/task/v2/shim.proto) protocol. +[Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol. + +The message and service definitions are auto-generated from protobuf source files under `vendor/` +by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not +edit those auto-generated source files. + +If upgrading/modification is needed, please follow the steps: + - Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'. + - Re-generate the source files by `cargo build --features=generate_bindings`. + - Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization. ## Usage Add `containerd-shim-client` as a dependency in your `Cargo.toml` diff --git a/crates/shim-protos/src/lib.rs b/crates/shim-protos/src/lib.rs index a00c14ed..fa737c7f 100644 --- a/crates/shim-protos/src/lib.rs +++ b/crates/shim-protos/src/lib.rs @@ -14,52 +14,7 @@ limitations under the License. */ -//! `containerd-shim-protos` contains TTRPC bindings and client/server code to interact with -//! containerd's runtime v2 shims. -//! -//! # Runtime -//! This crate is mainly expected to be useful to interact with containerd's shim runtime. -//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd. -//! The shim API is minimal and scoped to the execution lifecycle of a container. -//! -//! To learn how containerd's shim v2 runtime works in details, please refer to the [documentation](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md). -//! -//! # Design -//! The `containerd-shim-protos` crate provides [Protobuf](https://github.com/protocolbuffers/protobuf.git) message -//! and [TTRPC](https://github.com/containerd/ttrpc.git) service definitions for the -//! [Containerd shim v2](https://github.com/containerd/containerd/blob/main/runtime/v2/task/shim.proto) protocol. -//! -//! The message and service definitions are auto-generated from protobuf source files under `vendor/` -//! by using [ttrpc-codegen](https://github.com/containerd/ttrpc-rust/tree/master/ttrpc-codegen). So please do not -//! edit those auto-generated source files. -//! -//! If upgrading/modification is needed, please follow the steps: -//! - Synchronize the latest protobuf source files from the upstream projects into directory 'vendor/'. -//! - Re-generate the source files by `cargo build --features=generate_bindings`. -//! - Commit the synchronized protobuf source files and auto-generated source files, keeping them in synchronization. -//! -//! # Examples -//! -//! Here is a quick example how to use the crate: -//! ```no_run -//! use containerd_shim_protos as client; -//! -//! use client::api; -//! use client::ttrpc::context::Context; -//! -//! // Create TTRPC client -//! let client = client::Client::connect("unix:///socket.sock").unwrap(); -//! -//! // Get task client -//! let task_client = client::TaskClient::new(client); -//! let context = Context::default(); -//! -//! // Send request and receive response -//! let request = api::ConnectRequest::default(); -//! let response = task_client.connect(Context::default(), &request); -//! ``` -//! - +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] #![allow(warnings)] pub use protobuf; diff --git a/crates/shim/Cargo.toml b/crates/shim/Cargo.toml index 36a7bbb5..9cc0cd8c 100644 --- a/crates/shim/Cargo.toml +++ b/crates/shim/Cargo.toml @@ -22,6 +22,7 @@ async = [ "signal-hook-tokio", "tokio", ] +docs = [] [[example]] name = "skeleton_async" @@ -36,7 +37,7 @@ containerd-shim-protos = { path = "../shim-protos", version = "0.5.0" } go-flag = "0.1.0" lazy_static = "1.4.0" libc.workspace = true -log = { workspace = true, features = ["std"]} +log = { workspace = true, features = ["std"] } nix.workspace = true oci-spec.workspace = true page_size = "0.6.0" @@ -49,8 +50,10 @@ time.workspace = true # Async dependencies async-trait = { workspace = true, optional = true } -futures = { workspace = true, optional = true} -signal-hook-tokio = { version = "0.3.1", optional = true, features = ["futures-v0_3"]} +futures = { workspace = true, optional = true } +signal-hook-tokio = { version = "0.3.1", optional = true, features = [ + "futures-v0_3", +] } tokio = { workspace = true, features = ["full"], optional = true } [target.'cfg(target_os = "linux")'.dependencies] @@ -62,7 +65,7 @@ command-fds = "0.2.1" [target.'cfg(windows)'.dependencies] mio = { version = "0.8", features = ["os-ext", "os-poll"] } os_pipe.workspace = true -windows-sys = {version = "0.48.0", features = [ +windows-sys = { version = "0.48.0", features = [ "Win32_Foundation", "Win32_System_WindowsProgramming", "Win32_System_Console", @@ -70,7 +73,10 @@ windows-sys = {version = "0.48.0", features = [ "Win32_Security", "Win32_Storage_FileSystem", "Win32_System_Threading", - ]} +] } [dev-dependencies] tempfile = "3.6" + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/shim/README.md b/crates/shim/README.md index 9271812d..7620e72f 100644 --- a/crates/shim/README.md +++ b/crates/shim/README.md @@ -10,6 +10,22 @@ Rust crate to ease runtime v2 shim implementation. It replicates same [shim.Run](https://github.com/containerd/containerd/blob/dbef1d56d7ebc05bc4553d72c419ed5ce025b05d/runtime/v2/example/cmd/main.go) API offered by containerd's shim v2 runtime implementation written in Go. +## Runtime + +Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd. +The shim API is minimal and scoped to the execution lifecycle of a container. + +This crate simplifies shim v2 runtime development for containerd. It handles common tasks such +as command line parsing, setting up shim's TTRPC server, logging, events, etc. + +Clients are expected to implement [Shim] and [Task] traits with task handling routines. +This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go). + +Once implemented, shim's bootstrap code is as easy as: +```rust +shim::run::("io.containerd.empty.v1") +``` + ## Look and feel The API is very similar to the one offered by Go version: @@ -73,7 +89,6 @@ impl shim::Task for Service { fn main() { shim::run::("io.containerd.empty.v1") } - ``` ## How to use with containerd @@ -97,7 +112,7 @@ $ sudo ctr run --rm --runtime ./target/debug/examples/skeleton docker.io/library Or manually: -``` +```bash $ touch log # Run containerd in background diff --git a/crates/shim/src/lib.rs b/crates/shim/src/lib.rs index 2ec2f8f5..7de8b05e 100644 --- a/crates/shim/src/lib.rs +++ b/crates/shim/src/lib.rs @@ -14,23 +14,7 @@ limitations under the License. */ -//! A library to implement custom runtime v2 shims for containerd. -//! -//! # Runtime -//! Runtime v2 introduces a first class shim API for runtime authors to integrate with containerd. -//! The shim API is minimal and scoped to the execution lifecycle of a container. -//! -//! This crate simplifies shim v2 runtime development for containerd. It handles common tasks such -//! as command line parsing, setting up shim's TTRPC server, logging, events, etc. -//! -//! Clients are expected to implement [Shim] and [Task] traits with task handling routines. -//! This generally replicates same API as in Go [version](https://github.com/containerd/containerd/blob/main/runtime/v2/example/cmd/main.go). -//! -//! Once implemented, shim's bootstrap code is as easy as: -//! ```text -//! shim::run::("io.containerd.empty.v1") -//! ``` -//! +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] use std::{collections::hash_map::DefaultHasher, fs::File, hash::Hasher, path::PathBuf}; #[cfg(unix)] diff --git a/crates/snapshots/Cargo.toml b/crates/snapshots/Cargo.toml index 1c4b6d3f..c80cdbb4 100644 --- a/crates/snapshots/Cargo.toml +++ b/crates/snapshots/Cargo.toml @@ -14,6 +14,9 @@ license.workspace = true repository.workspace = true homepage.workspace = true +[features] +docs = [] + [dependencies] async-stream = "0.3.3" futures.workspace = true @@ -34,3 +37,6 @@ simple_logger = { version = "4.0", default-features = false } [build-dependencies] tonic-build.workspace = true + +[package.metadata.docs.rs] +features = ["docs"] diff --git a/crates/snapshots/src/lib.rs b/crates/snapshots/src/lib.rs index 84d7e1d0..5604fd09 100644 --- a/crates/snapshots/src/lib.rs +++ b/crates/snapshots/src/lib.rs @@ -14,41 +14,7 @@ limitations under the License. */ -//! Remote snapshotter extension for containerd. -//! -//! Snapshots crate implements containerd's proxy plugin for snapshotting. It aims hide the underlying -//! complexity of GRPC interfaces, streaming and request/response conversions and provide one -//! [crate::Snapshotter] trait to implement. -//! -//! # Proxy plugins -//! A proxy plugin is configured using containerd's config file and will be loaded alongside the -//! internal plugins when containerd is started. These plugins are connected to containerd using a -//! local socket serving one of containerd's GRPC API services. Each plugin is configured with a -//! type and name just as internal plugins are. -//! -//! # How to use from containerd -//! Add the following to containerd's configuration file: -//! ```toml -//! [proxy_plugins] -//! [proxy_plugins.custom] -//! type = "snapshot" -//! address = "/tmp/snap2.sock" -//! ``` -//! Start containerd daemon: -//! ```bash -//! containerd --config /path/config.toml -//! ``` -//! -//! Run remote snapshotter instance: -//! ```bash -//! $ cargo run --example snapshotter /tmp/snap2.sock -//! ``` -//! Now specify `custom` snapshotter when pulling an image with `ctr`: -//! ```bash -//! $ ctr i pull --snapshotter custom docker.io/library/hello-world:latest -//! ``` -//! - +#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] // No way to derive Eq with tonic :( // See https://github.com/hyperium/tonic/issues/1056 #![allow(clippy::derive_partial_eq_without_eq)]