From fcdc2161768daedecdbc23b12de521b7dcb21d80 Mon Sep 17 00:00:00 2001 From: neonphog Date: Fri, 15 Nov 2024 15:52:39 -0700 Subject: [PATCH 01/14] create the bootstrap spec --- Cargo.lock | 4 + Cargo.toml | 1 + crates/boot_srv/Cargo.toml | 13 ++++ crates/boot_srv/src/lib.rs | 150 +++++++++++++++++++++++++++++++++++++ 4 files changed, 168 insertions(+) create mode 100644 crates/boot_srv/Cargo.toml create mode 100644 crates/boot_srv/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index 07ec925..9c4eafc 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -33,6 +33,10 @@ dependencies = [ "serde_json", ] +[[package]] +name = "kitsune2_boot_srv" +version = "0.0.1-alpha" + [[package]] name = "memchr" version = "2.7.4" diff --git a/Cargo.toml b/Cargo.toml index c910df1..9381508 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,7 @@ [workspace] members = [ "crates/api", + "crates/boot_srv", ] resolver = "2" diff --git a/crates/boot_srv/Cargo.toml b/crates/boot_srv/Cargo.toml new file mode 100644 index 0000000..411096f --- /dev/null +++ b/crates/boot_srv/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "kitsune2_boot_srv" +version = "0.0.1-alpha" +description = "p2p / dht communication framework api" +license = "Apache-2.0" +homepage = "https://github.com/holochain/kitsune2" +documentation = "https://docs.rs/kitsune2_boot_srv" +authors = ["Holochain Core Dev Team "] +keywords = ["holochain", "holo", "p2p", "dht", "networking"] +categories = ["network-programming"] +edition = "2021" + +[dependencies] diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs new file mode 100644 index 0000000..90369a4 --- /dev/null +++ b/crates/boot_srv/src/lib.rs @@ -0,0 +1,150 @@ +#![deny(missing_docs)] +//! Kitsune2 boot server is an HTTP REST server for handling bootstrapping +//! discovery of peer network reachability in p2p applications. +//! +//! Despite being in the kitsune2 repo, `boot_srv` and `boot_cli` do not depend +//! on any Kitsune2 crates. This is to ensure the bootstrapping functionality +//! is well-defined, self-contained, easily testable in isolation, and +//! usable for projects that don't choose to make use of Kitsune2 itself. +//! +//! That being said, the boot server and client are designed to transfer the +//! `AgentInfoSigned` data type defined in the `kitsune2_api` crate. Since +//! the canonical encoding of that type is JSON, we just redefine a subset +//! of the schema here, and only validate the parts required for bootstrapping. +//! +//! For additional details, please see the [spec]. + +/// This is a documentation module containing the kitsune2_boot spec. +/// +/// #### 1. Types +/// +/// - `Base64Agent` - base64UrlNoPad safe encoded string agent id. +/// - `Base64Space` - base64UrlNoPad safe encoded string space id. +/// - `Base64Sig` - base64UrlNoPad safe encoded string crypto signature. +/// - `Json` - string containing json that can be decoded. +/// - `I64` - string contaning an i64 number. +/// +/// ```text +/// AgentInfoSigned = { "agentInfo": Json, "signature": Base64Sig } +/// AgentInfo = { +/// "agent": Base64Agent, +/// "space": Base64Space, +/// "createdAt": I64, +/// "expiresAt": I64, +/// "isTombstone": boolean +/// } +/// ``` +/// +/// Any other properties on these objects will be ignored and pass through. +/// +/// #### 2. REST API +/// +/// ##### 2.1. In Brief +/// +/// ```text +/// ErrResponse = { "error": string } +/// OkResponse = {} +/// ListResponse = [ AgentInfoSigned, .. ] +/// ``` +/// +/// - `PUT /boot/Base64Space/Base64Agent` +/// - Request Body: `AgentInfoSigned` +/// - Response Body: `OkResponse | ErrResponse` +/// - `GET /boot/Base64Space` +/// - Response Body: `ListResponse | ErrResponse` +/// - `GET /` +/// - Response Body: `OkResponse | ErrResponse` +/// +/// ##### 2.2. Publishing info to the boot server. +/// +/// A `PUT` on `/boot/Base64Space/Base64Agent` with an `AgentInfoSigned` +/// json object as the request body. +/// +/// - The server MUST reject the request if the body is > 1024 bytes. +/// - The server MUST reject the request if `createdAt` is not within +/// 3 minutes in either direction of the server time. +/// - The server MUST reject the request if `expiresAt` is in the past. +/// - The server MUST reject the request if `signature` is invalid vs +/// the `agentInfo`. +/// - If `isTombstone` is `true`, the server MUST delete any existing +/// info being held. +/// - If `isTombstone` is `false`, the server MAY begin storing the info. +/// See section 3. on storage strategies below. +/// +/// ##### 2.3. Listing data stored on the boot server. +/// +/// A `GET` on `/boot/Base64Space`. +/// +/// - The server MUST respond with a complete list of stored infos. +/// - If there are no infos stored at this space, the server MUST return +/// an empty list (`[]`). +/// - The only reason a server MAY return an `ErrResponse` for this request +/// is in the case of internal server error. +/// +/// ##### 2.4. Health check. +/// +/// A `GET` on `/`. +/// +/// - The server, in general, SHOULD return `OkResponse` to this request. +/// - The server MAY return `ErrResponse` for internal errors or some other +/// inability to continue serving correctly. +/// +/// #### 3. Storage Strategies +/// +/// ##### 3.1. The Future +/// +/// It is the intention to someday in the future to add a "trusted" strategy, +/// that will be triggerd via a new api, perhaps `/registerTrust/Base64Space`. +/// +/// Even when that API is implemented, however, the default strategy defined +/// next will be used on all spaces that have not been registered with a +/// different strategy. Therefore, we can proceed for now without consideration +/// for any other future strategies. +/// +/// ##### 3.2. The "Default" Storage Strategy +/// +/// Assumptions: +/// +/// - We don't want to store unbounded count infos in each space. +/// - We like storing long-running reliable nodes. +/// - We don't want to ONLY store long-running nodes to avoid eclipse scenarios. +/// +/// The solution put forth here is to allocate half our storage space to +/// long-running nodes, and the other half to whoever has most recently +/// published an info. The strategy for accomplishing this is defined here: +/// +/// Consider "the store" acting as a stack. It can be implemented in any manner, +/// but the following strategy assumes new entries are added to the end, +/// and when any entries are removed, the indexes of any items after them +/// will be decrimented. +/// +/// - The server SHOULD provide a configurable per-space max info count. +/// For the duration of this document, that value will be called MAX_INFOS. +/// It is recommended to default that value to `32`. +/// - The server SHOULD delete expired infos periodically. +/// - If the server is already storing an agent, and a `PUT` with a newer +/// `createdAt` arrives, the existing entry MUST be replaced. +/// - If the store count is < MAX_INFOS, the server MUST push the info +/// onto the stack. +/// - If the store count is >= MAX_INFOS, the server MUST delete the entry +/// at MAX_INFOS / 2 and then push the info onto the stack. +/// +/// #### 3. Rate Limiting +/// +/// Info count within a space is limited by the storage strategy above. But +/// space count within a server is unbounded. While servers will likely want +/// to limit request counts in general, we are also going to have to take some +/// special care with PUT requests that result in creation of a new space that +/// was not previously tracked in order to mitigate attacks. +/// +/// - A server SHOULD delete any spaces that no longer contain agents. +/// - A server SHOULD decide a max count of spaces it intends to support +/// (based on available memory or disk space for storing agents within those +/// spaces), and then return error 429 beyond that. +/// - A server MAY make the above max space count configurable. +/// - A server SHOULD track the IP addresses of clients that make PUT requests +/// which result in space creation, and error with 429 if that frequency +/// is beyond a limit. +/// - A server MAY make this limit configurable. +#[cfg(doc)] +pub mod spec {} From 8711baa88d665b7c28613237226fbdfbba935022 Mon Sep 17 00:00:00 2001 From: David Braden Date: Fri, 15 Nov 2024 15:57:21 -0700 Subject: [PATCH 02/14] Update crates/boot_srv/src/lib.rs --- crates/boot_srv/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 90369a4..ebf6521 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -129,7 +129,7 @@ /// - If the store count is >= MAX_INFOS, the server MUST delete the entry /// at MAX_INFOS / 2 and then push the info onto the stack. /// -/// #### 3. Rate Limiting +/// #### 4. Rate Limiting /// /// Info count within a space is limited by the storage strategy above. But /// space count within a server is unbounded. While servers will likely want From 0347f864d793abb37843000ce269d15769581c3a Mon Sep 17 00:00:00 2001 From: David Braden Date: Mon, 18 Nov 2024 16:55:53 -0700 Subject: [PATCH 03/14] Apply suggestions from code review Co-authored-by: Jost Schulte <28270981+jost-s@users.noreply.github.com> --- crates/boot_srv/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index ebf6521..6f9be10 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -22,7 +22,7 @@ /// - `Base64Space` - base64UrlNoPad safe encoded string space id. /// - `Base64Sig` - base64UrlNoPad safe encoded string crypto signature. /// - `Json` - string containing json that can be decoded. -/// - `I64` - string contaning an i64 number. +/// - `I64` - string containing an i64 number. /// /// ```text /// AgentInfoSigned = { "agentInfo": Json, "signature": Base64Sig } @@ -93,7 +93,7 @@ /// /// ##### 3.1. The Future /// -/// It is the intention to someday in the future to add a "trusted" strategy, +/// It is the intention someday in the future to add a "trusted" strategy, /// that will be triggerd via a new api, perhaps `/registerTrust/Base64Space`. /// /// Even when that API is implemented, however, the default strategy defined From ba378706def38d01b506edb72601a636a73ec458 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 08:21:15 -0700 Subject: [PATCH 04/14] cargo lock --- Cargo.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ae38146..80fff2d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -94,6 +94,10 @@ dependencies = [ "tokio", ] +[[package]] +name = "kitsune2_boot_srv" +version = "0.0.1-alpha" + [[package]] name = "libc" version = "0.2.162" @@ -110,10 +114,6 @@ dependencies = [ "scopeguard", ] -[[package]] -name = "kitsune2_boot_srv" -version = "0.0.1-alpha" - [[package]] name = "memchr" version = "2.7.4" From dd48b48f27a04f078fe82d3a77af60d6df60a43c Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:17:56 -0700 Subject: [PATCH 05/14] review comments --- crates/boot_srv/src/lib.rs | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 6f9be10..69b9f4b 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -18,11 +18,18 @@ /// /// #### 1. Types /// -/// - `Base64Agent` - base64UrlNoPad safe encoded string agent id. -/// - `Base64Space` - base64UrlNoPad safe encoded string space id. -/// - `Base64Sig` - base64UrlNoPad safe encoded string crypto signature. +/// All base64 in this spec uses: +/// +/// The url safe alphabet (with `-` and `_`) and no padding characters (`=`) +/// added when encoding or required when decoding. +/// +/// - `Base64Agent` - base64UrlSafeNoPad encoded string agent id. +/// - `Base64Space` - base64UrlSafeNoPad encoded string space id. +/// - `Base64Sig` - base64UrlSafeNoPad encoded string crypto signature. /// - `Json` - string containing json that can be decoded. -/// - `I64` - string containing an i64 number. +/// - `I64` - string containing an i64 number indicating the number of +/// microseconds since the unix epoch. Since the unix epoch +/// is canonically defined in UTC, the timestamp is also in UTC. /// /// ```text /// AgentInfoSigned = { "agentInfo": Json, "signature": Base64Sig } From 5e4fc8768a7dd43757a8b4c6d2ffc895208a50a0 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:20:14 -0700 Subject: [PATCH 06/14] address review comment --- crates/boot_srv/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 69b9f4b..e049255 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -59,7 +59,7 @@ /// - Response Body: `OkResponse | ErrResponse` /// - `GET /boot/Base64Space` /// - Response Body: `ListResponse | ErrResponse` -/// - `GET /` +/// - `GET /health` /// - Response Body: `OkResponse | ErrResponse` /// /// ##### 2.2. Publishing info to the boot server. @@ -90,7 +90,7 @@ /// /// ##### 2.4. Health check. /// -/// A `GET` on `/`. +/// A `GET` on `/health`. /// /// - The server, in general, SHOULD return `OkResponse` to this request. /// - The server MAY return `ErrResponse` for internal errors or some other From a2338e688dcb6793f7a37065d85d69fa9f454d6a Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:22:24 -0700 Subject: [PATCH 07/14] review comment --- crates/boot_srv/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index e049255..9a8150d 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -71,6 +71,7 @@ /// - The server MUST reject the request if `createdAt` is not within /// 3 minutes in either direction of the server time. /// - The server MUST reject the request if `expiresAt` is in the past. +/// - The server MUST reject the request if `expiresAt <= createdAt`. /// - The server MUST reject the request if `signature` is invalid vs /// the `agentInfo`. /// - If `isTombstone` is `true`, the server MUST delete any existing From d584bcb839c64b96a732d6aea9e96873d9979b11 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:30:41 -0700 Subject: [PATCH 08/14] review comment --- crates/boot_srv/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 9a8150d..ea81b63 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -75,7 +75,8 @@ /// - The server MUST reject the request if `signature` is invalid vs /// the `agentInfo`. /// - If `isTombstone` is `true`, the server MUST delete any existing -/// info being held. +/// info being held matching the `space` and `agent` and with a `createdAt` +/// less than the `createdAt` of the tombstone record. /// - If `isTombstone` is `false`, the server MAY begin storing the info. /// See section 3. on storage strategies below. /// From 84799bc759c5b2200b34e0d7036a6eaa062c1a98 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:34:42 -0700 Subject: [PATCH 09/14] review comment --- crates/boot_srv/src/lib.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index ea81b63..4d25d44 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -72,6 +72,8 @@ /// 3 minutes in either direction of the server time. /// - The server MUST reject the request if `expiresAt` is in the past. /// - The server MUST reject the request if `expiresAt <= createdAt`. +/// - The server MUST reject the request if `expiresAt - createdAt` is +/// more than 30 minutes. /// - The server MUST reject the request if `signature` is invalid vs /// the `agentInfo`. /// - If `isTombstone` is `true`, the server MUST delete any existing From 512b42107d32b78b82c6b4ad6a54f17774113663 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:37:08 -0700 Subject: [PATCH 10/14] review comment --- crates/boot_srv/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 4d25d44..e0a9797 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -131,7 +131,8 @@ /// /// - The server SHOULD provide a configurable per-space max info count. /// For the duration of this document, that value will be called MAX_INFOS. -/// It is recommended to default that value to `32`. +/// It is recommended to default that value to `32` to keep the maximum +/// response size from a request to around 32KiB. /// - The server SHOULD delete expired infos periodically. /// - If the server is already storing an agent, and a `PUT` with a newer /// `createdAt` arrives, the existing entry MUST be replaced. From 984dc99ec51274bfa7bd60245f44daf089c972a4 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 14:42:10 -0700 Subject: [PATCH 11/14] review comment --- crates/boot_srv/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index e0a9797..e8d674d 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -129,7 +129,8 @@ /// and when any entries are removed, the indexes of any items after them /// will be decrimented. /// -/// - The server SHOULD provide a configurable per-space max info count. +/// - The server SHOULD allow setting the maximum number of infos that will be +/// allowed in a single space. /// For the duration of this document, that value will be called MAX_INFOS. /// It is recommended to default that value to `32` to keep the maximum /// response size from a request to around 32KiB. From d49c23eb24e6960bb5847ed030e062a9d1d0f579 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 16:18:05 -0700 Subject: [PATCH 12/14] review comment --- crates/boot_srv/src/lib.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index e8d674d..76520d3 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -159,5 +159,18 @@ /// which result in space creation, and error with 429 if that frequency /// is beyond a limit. /// - A server MAY make this limit configurable. +/// +/// #### 5. Client Recommendations +/// +/// - In the case of server unreachable or 500 error, a client should use +/// an exponential backoff strategy to avoid stressing the server when +/// it does come back online. +/// - A client should poll the bootstrap server on an interval >= 5 minutes +/// to balance getting new infos to avoid partitioning without worry +/// of hitting the rate limit. +/// - A client, in general, should set expiration to 20 minutes beyond +/// the info creation time. +/// - A client, in general, should re-publish a new info on a 15 minute +/// interval. #[cfg(doc)] pub mod spec {} From 4b12a8b8d4b6c042bb3f0e2d072bd5039396c379 Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 16:19:58 -0700 Subject: [PATCH 13/14] review comment --- crates/boot_srv/src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/boot_srv/src/lib.rs b/crates/boot_srv/src/lib.rs index 76520d3..2c94fee 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/boot_srv/src/lib.rs @@ -54,17 +54,17 @@ /// ListResponse = [ AgentInfoSigned, .. ] /// ``` /// -/// - `PUT /boot/Base64Space/Base64Agent` +/// - `PUT /boot//` /// - Request Body: `AgentInfoSigned` /// - Response Body: `OkResponse | ErrResponse` -/// - `GET /boot/Base64Space` +/// - `GET /boot/` /// - Response Body: `ListResponse | ErrResponse` /// - `GET /health` /// - Response Body: `OkResponse | ErrResponse` /// /// ##### 2.2. Publishing info to the boot server. /// -/// A `PUT` on `/boot/Base64Space/Base64Agent` with an `AgentInfoSigned` +/// A `PUT` on `/boot//` with an `AgentInfoSigned` /// json object as the request body. /// /// - The server MUST reject the request if the body is > 1024 bytes. @@ -84,7 +84,7 @@ /// /// ##### 2.3. Listing data stored on the boot server. /// -/// A `GET` on `/boot/Base64Space`. +/// A `GET` on `/boot/`. /// /// - The server MUST respond with a complete list of stored infos. /// - If there are no infos stored at this space, the server MUST return From edc254629867487c5bb99ac47f6ebf531dc1d96d Mon Sep 17 00:00:00 2001 From: neonphog Date: Tue, 19 Nov 2024 16:26:27 -0700 Subject: [PATCH 14/14] review comment --- Cargo.lock | 2 +- Cargo.toml | 2 +- crates/{boot_srv => bootstrap_srv}/Cargo.toml | 4 +-- crates/{boot_srv => bootstrap_srv}/src/lib.rs | 31 ++++++++++--------- 4 files changed, 20 insertions(+), 19 deletions(-) rename crates/{boot_srv => bootstrap_srv}/Cargo.toml (79%) rename crates/{boot_srv => bootstrap_srv}/src/lib.rs (87%) diff --git a/Cargo.lock b/Cargo.lock index 80fff2d..cd5f77c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -95,7 +95,7 @@ dependencies = [ ] [[package]] -name = "kitsune2_boot_srv" +name = "kitsune2_bootstrap_srv" version = "0.0.1-alpha" [[package]] diff --git a/Cargo.toml b/Cargo.toml index 095f8c8..fe492e0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [workspace] members = [ "crates/api", - "crates/boot_srv", + "crates/bootstrap_srv", ] resolver = "2" diff --git a/crates/boot_srv/Cargo.toml b/crates/bootstrap_srv/Cargo.toml similarity index 79% rename from crates/boot_srv/Cargo.toml rename to crates/bootstrap_srv/Cargo.toml index 411096f..23ab43a 100644 --- a/crates/boot_srv/Cargo.toml +++ b/crates/bootstrap_srv/Cargo.toml @@ -1,10 +1,10 @@ [package] -name = "kitsune2_boot_srv" +name = "kitsune2_bootstrap_srv" version = "0.0.1-alpha" description = "p2p / dht communication framework api" license = "Apache-2.0" homepage = "https://github.com/holochain/kitsune2" -documentation = "https://docs.rs/kitsune2_boot_srv" +documentation = "https://docs.rs/kitsune2_bootstrap_srv" authors = ["Holochain Core Dev Team "] keywords = ["holochain", "holo", "p2p", "dht", "networking"] categories = ["network-programming"] diff --git a/crates/boot_srv/src/lib.rs b/crates/bootstrap_srv/src/lib.rs similarity index 87% rename from crates/boot_srv/src/lib.rs rename to crates/bootstrap_srv/src/lib.rs index 2c94fee..a3eede7 100644 --- a/crates/boot_srv/src/lib.rs +++ b/crates/bootstrap_srv/src/lib.rs @@ -1,20 +1,21 @@ #![deny(missing_docs)] -//! Kitsune2 boot server is an HTTP REST server for handling bootstrapping +//! Kitsune2 bootstrap server is an HTTP REST server for handling bootstrapping //! discovery of peer network reachability in p2p applications. //! -//! Despite being in the kitsune2 repo, `boot_srv` and `boot_cli` do not depend -//! on any Kitsune2 crates. This is to ensure the bootstrapping functionality -//! is well-defined, self-contained, easily testable in isolation, and -//! usable for projects that don't choose to make use of Kitsune2 itself. +//! Despite being in the kitsune2 repo, `bootstrap_srv` and `bootstrap_cli` +//! do not depend on any Kitsune2 crates. This is to ensure the bootstrapping +//! functionality is well-defined, self-contained, easily testable in +//! isolation, and usable for projects that don't choose to make use of +//! Kitsune2 itself. //! -//! That being said, the boot server and client are designed to transfer the -//! `AgentInfoSigned` data type defined in the `kitsune2_api` crate. Since +//! That being said, the bootstrap server and client are designed to transfer +//! the `AgentInfoSigned` data type defined in the `kitsune2_api` crate. Since //! the canonical encoding of that type is JSON, we just redefine a subset //! of the schema here, and only validate the parts required for bootstrapping. //! //! For additional details, please see the [spec]. -/// This is a documentation module containing the kitsune2_boot spec. +/// This is a documentation module containing the kitsune2_bootstrap spec. /// /// #### 1. Types /// @@ -54,18 +55,18 @@ /// ListResponse = [ AgentInfoSigned, .. ] /// ``` /// -/// - `PUT /boot//` +/// - `PUT /bootstrap//` /// - Request Body: `AgentInfoSigned` /// - Response Body: `OkResponse | ErrResponse` -/// - `GET /boot/` +/// - `GET /bootstrap/` /// - Response Body: `ListResponse | ErrResponse` /// - `GET /health` /// - Response Body: `OkResponse | ErrResponse` /// -/// ##### 2.2. Publishing info to the boot server. +/// ##### 2.2. Publishing info to the bootstrap server. /// -/// A `PUT` on `/boot//` with an `AgentInfoSigned` -/// json object as the request body. +/// A `PUT` on `/bootstrap//` with an +/// `AgentInfoSigned` json object as the request body. /// /// - The server MUST reject the request if the body is > 1024 bytes. /// - The server MUST reject the request if `createdAt` is not within @@ -82,9 +83,9 @@ /// - If `isTombstone` is `false`, the server MAY begin storing the info. /// See section 3. on storage strategies below. /// -/// ##### 2.3. Listing data stored on the boot server. +/// ##### 2.3. Listing data stored on the bootstrap server. /// -/// A `GET` on `/boot/`. +/// A `GET` on `/bootstrap/`. /// /// - The server MUST respond with a complete list of stored infos. /// - If there are no infos stored at this space, the server MUST return