From f2e5c0e723e85c32c706fc9d85ee389c04a19649 Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Fri, 23 Feb 2024 14:45:18 -0500 Subject: [PATCH 01/13] Improve the documentation for the README. Fix the GLIB issue caused by incompatible Docker images. --- Dockerfile | 2 +- README.md | 17 ++++++++++++----- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/Dockerfile b/Dockerfile index 097a0da..8911692 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM rust:1.76 AS BUILD +FROM rust:1.76-buster AS BUILD ENV APP_NAME=mirror-server ENV APP_HOME=/srv/${APP_NAME} diff --git a/README.md b/README.md index c165ec7..e045668 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,16 @@ A simple server for mirroring HTTP requests for testing. ## Install +### Docker Image + +Run via Docker using: + +```bash +docker run code.birch-tree.net/dorian/mirror-server:latest +``` + +### Debian Package + Download the DEB file, and install it: ```bash @@ -26,12 +36,9 @@ curl "${REPO_URL}/${VERSION}/mirror-server_${VERSION}_amd64.deb" sudo dpkg -i "mirror-server-${VERSION}_amd64.deb" ``` +Afterward you can run using `mirror-server` + ## TODO -* [x] Migrate actix to axum for easier maintainability. -* [x] Add mirroring of JSON request. -* [x] Add logging to server. -* [x] Create Docker image for mirror-server for easier distribution. -* [x] Add publishing of DEB and Docker image to DroneCI. * [ ] Add documentation to the API. * [ ] Publish crate on . -- 2.40.1 From 31164bc3affdf0d2c9c92af0f42a335c00fec3a0 Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Fri, 23 Feb 2024 14:51:02 -0500 Subject: [PATCH 02/13] Only run a Debian release on a tag. --- .drone.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.drone.yml b/.drone.yml index c398f79..e6b85b4 100644 --- a/.drone.yml +++ b/.drone.yml @@ -54,6 +54,9 @@ steps: from_secret: gitea-release-password depends_on: - test + when: + ref: + - refs/tags/* image_pull_secrets: - docker-config -- 2.40.1 From e89e1a394e616438c0fcfe4bf59b1f6bb76f0fc8 Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Fri, 23 Feb 2024 15:00:07 -0500 Subject: [PATCH 03/13] Only release a Docker image on a tag. --- .drone.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.drone.yml b/.drone.yml index e6b85b4..2c7f7d6 100644 --- a/.drone.yml +++ b/.drone.yml @@ -43,6 +43,9 @@ steps: - code.birch-tree.net/dorian/mirror-server:build depends_on: - test + when: + ref: + - refs/tags/* - name: create-debian-package image: code.birch-tree.net/dorian/mirror-server:build -- 2.40.1 From b5a2693119cb4043fabb46bfa58b261d6ead702f Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Fri, 23 Feb 2024 15:35:10 -0500 Subject: [PATCH 04/13] Fix issue with source code not ending up in the release. --- .drone.yml | 12 ++++++------ Dockerfile | 5 +---- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/.drone.yml b/.drone.yml index 2c7f7d6..8a7529b 100644 --- a/.drone.yml +++ b/.drone.yml @@ -43,9 +43,9 @@ steps: - code.birch-tree.net/dorian/mirror-server:build depends_on: - test - when: - ref: - - refs/tags/* +# when: +# ref: +# - refs/tags/* - name: create-debian-package image: code.birch-tree.net/dorian/mirror-server:build @@ -57,9 +57,9 @@ steps: from_secret: gitea-release-password depends_on: - test - when: - ref: - - refs/tags/* +# when: +# ref: +# - refs/tags/* image_pull_secrets: - docker-config diff --git a/Dockerfile b/Dockerfile index 8911692..3b9408f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -19,7 +19,7 @@ RUN cargo build \ && rm src/*.rs # Bring in the source -COPY ["src", "./src/"] +COPY ["./src/*", "./src/"] # Build the example API. RUN cargo build --release @@ -31,8 +31,5 @@ ENV APP_NAME=mirror-server ENV APP_HOME=/srv/${APP_NAME} RUN apt update -RUN mkdir -p ${APP_HOME} -WORKDIR ${APP_HOME} - COPY --from=BUILD ${APP_HOME}/target/release/${APP_NAME} /usr/local/bin/ CMD ${APP_NAME} \ No newline at end of file -- 2.40.1 From b991c30953a434ed940ad40d99b71d8d9d6fb28b Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Fri, 23 Feb 2024 15:41:43 -0500 Subject: [PATCH 05/13] Improve the documentation and ensure tags only are released. --- .drone.yml | 12 ++++++------ README.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.drone.yml b/.drone.yml index 8a7529b..2c7f7d6 100644 --- a/.drone.yml +++ b/.drone.yml @@ -43,9 +43,9 @@ steps: - code.birch-tree.net/dorian/mirror-server:build depends_on: - test -# when: -# ref: -# - refs/tags/* + when: + ref: + - refs/tags/* - name: create-debian-package image: code.birch-tree.net/dorian/mirror-server:build @@ -57,9 +57,9 @@ steps: from_secret: gitea-release-password depends_on: - test -# when: -# ref: -# - refs/tags/* + when: + ref: + - refs/tags/* image_pull_secrets: - docker-config diff --git a/README.md b/README.md index e045668..70f9995 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ A simple server for mirroring HTTP requests for testing. Run via Docker using: ```bash -docker run code.birch-tree.net/dorian/mirror-server:latest +docker run -p 8080:8080 code.birch-tree.net/dorian/mirror-server:latest ``` ### Debian Package -- 2.40.1 From 65898987a65512285e74cbdd47b4848493a32800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Fri, 23 Feb 2024 21:29:37 -0500 Subject: [PATCH 06/13] Initial documentation of crate. --- README.md | 24 ++++++++++++++++++++---- src/main.rs | 6 ++++++ 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 70f9995..7657602 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # mirror-server -A simple server for mirroring HTTP requests for testing. +A simple server for mirroring HTTP requests for testing. It is optimized for +working with REST API JSON calls, and catching headers. [![Build Status](https://ci.birch-tree.net/api/badges/dorian/mirror-server/status.svg)](https://ci.birch-tree.net/dorian/mirror-server) @@ -14,9 +15,14 @@ A simple server for mirroring HTTP requests for testing. * Install cargo-deb: `cargo install cargo-deb` * Create the DEB package: `cargo deb` * Faster builds using [cargo-watch](https://watchexec.github.io/#cargo-watch): `cargo watch -x run` +* Installing the binary locally from source: `cargo install --path .` ## Install +`mirror-server` is installable either by a local Cargo install or a Debian +package. Additionally `mirror-server` can be run as a Docker container using +the latest (or tagged) release. + ### Docker Image Run via Docker using: @@ -38,7 +44,17 @@ sudo dpkg -i "mirror-server-${VERSION}_amd64.deb" Afterward you can run using `mirror-server` -## TODO +## Usage -* [ ] Add documentation to the API. -* [ ] Publish crate on . +```bash +> mirror-server --help +A simple server for mirror HTTP requests for testing. + +Usage: mirror-server [OPTIONS] + +Options: + -p, --port Port to run on [default: 8080] + -i, --ips Listen to IP mask [default: 0.0.0.0] + -h, --help Print help + -V, --version Print version +``` diff --git a/src/main.rs b/src/main.rs index 95c8ff1..ced23d1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,9 @@ +#![warn(missing_docs)] + +#![doc = include_str!("../README.md")] +/// ## Usage +/// + use axum::{ extract::{Host, Json, OriginalUri}, http::{header::HeaderMap, Method}, -- 2.40.1 From aca5a57460df49619b82d05dc7a75953e690dce5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Fri, 23 Feb 2024 23:05:50 -0500 Subject: [PATCH 07/13] Add documentation of the main crate and first objects. --- src/main.rs | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/main.rs b/src/main.rs index ced23d1..967ab80 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,8 +1,4 @@ -#![warn(missing_docs)] - #![doc = include_str!("../README.md")] -/// ## Usage -/// use axum::{ extract::{Host, Json, OriginalUri}, @@ -16,6 +12,11 @@ use std::collections::BTreeMap; use tower_http::trace; use tracing::{info, warn, Level}; + +/// CLI arguments used by the [Parser]. +/// +/// Creates the usage and version information that is standard in a CLI +/// utility. #[derive(Parser)] #[command(author, version, about, long_about = None)] struct CliArgs { @@ -28,12 +29,18 @@ struct CliArgs { ips: String, } +/// The response consisting of the echoed request to the mirror-server. #[derive(Serialize, Deserialize, Debug, PartialEq)] struct EchoResponse { + /// The [Method] used in the request. method: String, + /// The path used in the request. path: String, + /// The original schema, hostname and port of the request. host: String, + /// The headers in the request. headers: BTreeMap, + /// (Optional) The JSON body in the request. #[serde(skip_serializing_if = "Option::is_none")] body: Option, } -- 2.40.1 From 762186ea2ff29a95c622d6c6c92165815fe3229e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 08:51:09 -0500 Subject: [PATCH 08/13] Improve the documentation of the crate. --- README.md | 10 +++++----- src/main.rs | 18 ++++++++++++++++-- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 7657602..002fd76 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ working with REST API JSON calls, and catching headers. * Create a DEB package: * Install cargo-deb: `cargo install cargo-deb` * Create the DEB package: `cargo deb` -* Faster builds using [cargo-watch](https://watchexec.github.io/#cargo-watch): `cargo watch -x run` +* Faster builds using [`cargo-watch`](https://watchexec.github.io/#cargo-watch): `cargo watch -x run` * Installing the binary locally from source: `cargo install --path .` ## Install @@ -27,8 +27,8 @@ the latest (or tagged) release. Run via Docker using: -```bash -docker run -p 8080:8080 code.birch-tree.net/dorian/mirror-server:latest +```console +$ docker run -p 8080:8080 code.birch-tree.net/dorian/mirror-server:latest ``` ### Debian Package @@ -46,8 +46,8 @@ Afterward you can run using `mirror-server` ## Usage -```bash -> mirror-server --help +```console +$ mirror-server --help A simple server for mirror HTTP requests for testing. Usage: mirror-server [OPTIONS] diff --git a/src/main.rs b/src/main.rs index 967ab80..180f10a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -13,7 +13,7 @@ use tower_http::trace; use tracing::{info, warn, Level}; -/// CLI arguments used by the [Parser]. +/// CLI arguments used by the [`Parser`]. /// /// Creates the usage and version information that is standard in a CLI /// utility. @@ -32,7 +32,7 @@ struct CliArgs { /// The response consisting of the echoed request to the mirror-server. #[derive(Serialize, Deserialize, Debug, PartialEq)] struct EchoResponse { - /// The [Method] used in the request. + /// The [`Method`] used in the request. method: String, /// The path used in the request. path: String, @@ -45,6 +45,15 @@ struct EchoResponse { body: Option, } +/// [`Handler`](axum::handler) for responding with a break-down of the captured request. +/// +/// Captures the request and responds with a JSON response of the elements of the request. +/// +/// TODO: Add a example of the JSON output of the response. +/// +/// ## Arguments +/// * `method` - The HTTP [`Method`] used for the request. i.e. `GET`, `POST`, `PATCH`, etc. +/// TODO: Document the rest of the arguments async fn echo_request( method: Method, original_uri: OriginalUri, @@ -80,6 +89,10 @@ async fn echo_request( Json(response) } +/// Create a [`Router`] to handling capture all HTTP requests to the server. +/// +/// Wires up a default catch-all route for the application. Also adds the tracing infrastructure +/// to capture requests. fn app() -> Router { Router::new().fallback(echo_request).layer( trace::TraceLayer::new_for_http() @@ -88,6 +101,7 @@ fn app() -> Router { ) } +/// The main application starts the mirror-server application. #[tokio::main] async fn main() { let cli_args = CliArgs::parse(); -- 2.40.1 From f14963a2c4d125dd3c019eec126deb3d8e2461bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 10:04:22 -0500 Subject: [PATCH 09/13] Add a sample curl and JSON response to the API. --- examples/sample-response.json | 15 +++++++++++++++ src/main.rs | 19 +++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 examples/sample-response.json diff --git a/examples/sample-response.json b/examples/sample-response.json new file mode 100644 index 0000000..a110a95 --- /dev/null +++ b/examples/sample-response.json @@ -0,0 +1,15 @@ +{ + "method": "PUT", + "path": "/api/testing", + "host": "localhost:8180", + "headers": { + "accept": "*/*", + "content-length": "18", + "content-type": "application/json", + "host": "localhost:8180", + "user-agent": "curl/7.68.0" + }, + "body": { + "hello": "world" + } +} diff --git a/src/main.rs b/src/main.rs index 180f10a..3c3a882 100644 --- a/src/main.rs +++ b/src/main.rs @@ -49,11 +49,26 @@ struct EchoResponse { /// /// Captures the request and responds with a JSON response of the elements of the request. /// -/// TODO: Add a example of the JSON output of the response. -/// /// ## Arguments /// * `method` - The HTTP [`Method`] used for the request. i.e. `GET`, `POST`, `PATCH`, etc. /// TODO: Document the rest of the arguments +/// +/// ## Example +/// +/// Sending a request using `curl`: +/// +/// ```console +/// $ curl -s -X PUT -D '{"hello": "world"}' -H 'Content-Type: application/json' \ +/// http://localhost:8080/api/testing | jq . +/// ``` +/// +/// Results in a JSON response: +/// +/// ```json +#[doc = include_str!("../examples/sample-response.json")] +/// ``` +/// + async fn echo_request( method: Method, original_uri: OriginalUri, -- 2.40.1 From 780ab23310d8421c771b66787998e07186de4b15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 12:34:19 -0500 Subject: [PATCH 10/13] Finish documenting the codebase. --- README.md | 31 +++++++++++++++++++++++++++++++ examples/sample-response.json | 15 --------------- src/main.rs | 22 +++++----------------- 3 files changed, 36 insertions(+), 32 deletions(-) delete mode 100644 examples/sample-response.json diff --git a/README.md b/README.md index 002fd76..a44b0a8 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,9 @@ Afterward you can run using `mirror-server` ## Usage +You can get all the options that `mirror-server` supports by running it with +the help option `--help` or `-h`: + ```console $ mirror-server --help A simple server for mirror HTTP requests for testing. @@ -58,3 +61,31 @@ Options: -h, --help Print help -V, --version Print version ``` + +After starting the server, you can send requests to it. Using `curl` you +can send `mirror-server` JSON requests: + +```console +$ curl -s -X PUT -D '{"hello": "world"}' -H 'Content-Type: application/json' \ + http://localhost:8080/api/testing | jq . +``` + +And `mirror-server` responds to requests with JSON responses: + +```json +{ + "method": "PUT", + "path": "/api/testing", + "host": "localhost:8180", + "headers": { + "accept": "*/*", + "content-length": "18", + "content-type": "application/json", + "host": "localhost:8080", + "user-agent": "curl/7.68.0" + }, + "body": { + "hello": "world" + } +} +``` diff --git a/examples/sample-response.json b/examples/sample-response.json deleted file mode 100644 index a110a95..0000000 --- a/examples/sample-response.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "method": "PUT", - "path": "/api/testing", - "host": "localhost:8180", - "headers": { - "accept": "*/*", - "content-length": "18", - "content-type": "application/json", - "host": "localhost:8180", - "user-agent": "curl/7.68.0" - }, - "body": { - "hello": "world" - } -} diff --git a/src/main.rs b/src/main.rs index 3c3a882..13a8c5e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -51,24 +51,12 @@ struct EchoResponse { /// /// ## Arguments /// * `method` - The HTTP [`Method`] used for the request. i.e. `GET`, `POST`, `PATCH`, etc. -/// TODO: Document the rest of the arguments +/// * `original_uri` - The URI used for the request. +/// * `host` - The hostname of the request. +/// * `header_map` - A map with the headers used during the request. +/// * `body` - An optional JSON body, if it is past in to the request. +/// Requires a header of `Content-Type: application/json` and a body passed in the request. /// -/// ## Example -/// -/// Sending a request using `curl`: -/// -/// ```console -/// $ curl -s -X PUT -D '{"hello": "world"}' -H 'Content-Type: application/json' \ -/// http://localhost:8080/api/testing | jq . -/// ``` -/// -/// Results in a JSON response: -/// -/// ```json -#[doc = include_str!("../examples/sample-response.json")] -/// ``` -/// - async fn echo_request( method: Method, original_uri: OriginalUri, -- 2.40.1 From 2cee5651e3d99521b0a9c63bc2320aaf4556e15c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 12:35:53 -0500 Subject: [PATCH 11/13] Bump the version for a new minor release. --- .drone.yml | 2 +- Cargo.toml | 2 +- README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.drone.yml b/.drone.yml index 2c7f7d6..88ec18d 100644 --- a/.drone.yml +++ b/.drone.yml @@ -36,7 +36,7 @@ steps: registry: code.birch-tree.net repo: code.birch-tree.net/dorian/mirror-server tags: - - 0.3.0 + - 0.3.1 - latest cache_from: - code.birch-tree.net/dorian/mirror-server:latest diff --git a/Cargo.toml b/Cargo.toml index b41e7eb..57f1ffa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "mirror-server" -version = "0.3.0" +version = "0.3.1" edition = "2021" authors = ["Dorian Pula "] description = "A simple server for mirror HTTP requests for testing." diff --git a/README.md b/README.md index a44b0a8..655f307 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ $ docker run -p 8080:8080 code.birch-tree.net/dorian/mirror-server:latest Download the DEB file, and install it: ```bash -VERSION=0.3.0 +VERSION=0.3.1 REPO_URL=https://code.birch-tree.net/api/packages/dorian/generic/mirror-server/ curl "${REPO_URL}/${VERSION}/mirror-server_${VERSION}_amd64.deb" sudo dpkg -i "mirror-server-${VERSION}_amd64.deb" -- 2.40.1 From 01063534ec7a9e7f5d57f31b04f2f848a9811fe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 12:38:29 -0500 Subject: [PATCH 12/13] Fix Docker build issue. --- Dockerfile | 1 + 1 file changed, 1 insertion(+) diff --git a/Dockerfile b/Dockerfile index 3b9408f..44f2097 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,6 +20,7 @@ RUN cargo build \ # Bring in the source COPY ["./src/*", "./src/"] +COPY ["README.md", "LICENSE", "."] # Build the example API. RUN cargo build --release -- 2.40.1 From 83b4e44b5f369311d98fa617a33d246615833a35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dorian=20Pu=C5=82a?= Date: Sat, 24 Feb 2024 13:55:56 -0500 Subject: [PATCH 13/13] Oops. COPY needs a directory for multiple files, so an ending slash. --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 44f2097..de0d199 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,7 +20,7 @@ RUN cargo build \ # Bring in the source COPY ["./src/*", "./src/"] -COPY ["README.md", "LICENSE", "."] +COPY ["README.md", "LICENSE", "./"] # Build the example API. RUN cargo build --release -- 2.40.1