From 3c1f5515ea1e1370ce22a9f3d0937c7a5959ef6c Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 15 Jul 2021 11:02:07 -0700 Subject: [PATCH 1/5] Rename viceroy-cli package to viceroy. --- Cargo.lock | 2 +- cli/Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index bf5af91b..27cc98f2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2084,7 +2084,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5fecdca9a5291cc2b8dcf7dc02453fee791a280f3743cb0905f8822ae463b3fe" [[package]] -name = "viceroy-cli" +name = "viceroy" version = "0.2.2" dependencies = [ "anyhow", diff --git a/cli/Cargo.toml b/cli/Cargo.toml index a0f52e1f..83576651 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "viceroy-cli" +name = "viceroy" description = "Viceroy is a local testing daemon for Compute@Edge." version = "0.2.2" authors = ["Fastly"] From 6f6e51a2be2bcef974848204715a0b6e107d3f78 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 15 Jul 2021 11:02:20 -0700 Subject: [PATCH 2/5] Update README to reflect Fastly CLI and crates.io releases. --- README.md | 73 ++++++++++++++++++------------------------------------- 1 file changed, 24 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 7193e175..285bca82 100644 --- a/README.md +++ b/README.md @@ -5,48 +5,19 @@ allows you to run services written against the Compute@Edge APIs on your local development machine, and allows you to configure testing backends for your service to communicate with. -In the near future, Viceroy will be packaged as part of the Fastly CLI and -integrate with other Compute@Edge workflows. But for the moment, you can use it -by hand, as described below. +Viceroy is normally used through the [Fastly CLI's `fastly compute serve` +command][cli], where it it fully integrated into the Compute@Edge workflows. +However, it is also a standalone open source tool with its own CLI and a +Rust library that can be embedded into your own testing infrastructure. + +[cli]: https://developer.fastly.com/learning/compute/testing/#running-a-local-testing-server ## Installation To install Viceroy, you'll need to first [install Rust](https://www.rust-lang.org/tools/install) if you haven't already. - -### Clone the repo - -You'll need to get a copy of the Viceroy source code locally, by cloning the -[Viceroy repo](https://github.com/fastly/Viceroy/) like so: - -``` -git clone git@github.com:fastly/Viceroy.git -cd Viceroy -git submodule update --recursive --init -``` - -### Install via Cargo - -Next, navigate to the `Viceroy` directory resulting from the `git clone` above, -and run: - -``` -cargo install --path cli -``` - -You should see a message that says `Installing viceroy-cli` followed by a large -number of compilation messages. The end result is that the `viceroy` command -is made available on your system. - -### Updating Viceroy - -To update Viceroy, navigate to the `Viceroy` directory you cloned above, and then: - -``` -git pull -git submodule update --recursive --init -cargo install --path cli -``` +Then run `cargo install viceroy`, which will download and build the latest +Viceroy release. ## Usage @@ -59,28 +30,22 @@ built by `fastly compute build`. The Fastly CLI should put the blob at viceroy bin/main.wasm ``` -This will start a local server (by default at: `http://127.0.0.1:7878`), which can be used to make requests to, and execute, your C@E Wasm module. This can be done by using [curl](https://curl.se/), or you can send a simple GET request by visiting the URL in your web browser. - -**NOTE:** Viceroy expects to find a `fastly.toml` manifest. It will look only in the -current directory by default; you can specify a path to the file using the -`--manifest-path` option. The manifest is used to configure backends, which we -describe next. +This will start a local server (by default at: `http://127.0.0.1:7878`), which can +be used to make requests to your Compute@Edge service locally. You can make requests +by using [curl](https://curl.se/), or you can send a simple GET request by visiting +the URL in your web browser. ### Configuring backends Most Compute@Edge services need to make requests to named backends (origin servers), which are normally configured using the Fastly UI. For testing with -Viceroy, you can specify backends in a **dedicated** TOML file, which you +Viceroy, you can specify backends in your `fastly.toml` file, which you provide to Viceroy using the `-C` flag: ``` -viceroy bin/main.wasm -C backends.toml +viceroy bin/main.wasm -C fastly.toml ``` -In the future, testing backends will be part of the `fastly.toml` manifest -managed by the Fastly CLI, but for now you should **not** use the `fastly.toml` -manifest, because the Fastly CLI will remove any additions you make. - Backends are specified in the TOML file within a `local_server.backends` section: @@ -141,6 +106,16 @@ particular: * Caching directives are ignored; no caching is ever performed. * Information about the TLS connection from the client is not available. +## Working with Viceroy's source + +Note that this repository uses Git submodules, so you will need to run + +``` +git submodule update --recursive --init +``` + +to pull down or update submodules. + ## Colophon ![Viceroy](doc/logo.png) From 1ebec56c262cdde27c6440db4c1139869e309b61 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 15 Jul 2021 11:33:37 -0700 Subject: [PATCH 3/5] Update package check with new cli package name --- scripts/publish.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/publish.rs b/scripts/publish.rs index c344227a..7bdeff8b 100644 --- a/scripts/publish.rs +++ b/scripts/publish.rs @@ -20,7 +20,7 @@ const VERIFY_TEMPDIR: &str = "verify-publishable"; /// The crates that we will publish. // // N.B. This list must be topologically sorted by dependencies. -const CRATES_TO_PUBLISH: &[&str] = &["viceroy-lib", "viceroy-cli"]; +const CRATES_TO_PUBLISH: &[&str] = &["viceroy-lib", "viceroy"]; /// The crates that we will NOT publish. // From 63ea327f72f86afb03a94d67cdbc3d394feb5e01 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 15 Jul 2021 12:32:43 -0700 Subject: [PATCH 4/5] Typo fix Co-authored-by: katelyn martin --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 285bca82..28c1d663 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ development machine, and allows you to configure testing backends for your service to communicate with. Viceroy is normally used through the [Fastly CLI's `fastly compute serve` -command][cli], where it it fully integrated into the Compute@Edge workflows. +command][cli], where it is fully integrated into Compute@Edge workflows. However, it is also a standalone open source tool with its own CLI and a Rust library that can be embedded into your own testing infrastructure. From 6afde7ed9eb3d434807329f8f6569c5ec71c20c1 Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 15 Jul 2021 13:11:27 -0700 Subject: [PATCH 5/5] Direct people to use Fastly CLI in more cases. --- README.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 28c1d663..b2b8da4c 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,27 @@ Rust library that can be embedded into your own testing infrastructure. ## Installation -To install Viceroy, you'll need to first +### Via the Fastly CLI + +As mentioned above, most users of Compute@Edge should do local testing via the +Fastly CLI, rather than working with Viceroy directly. Any [CLI release] of +version 0.34 or above supports local testing, and the workflow is documented +[here][cli]. + +[CLI release]: https://github.com/fastly/cli/releases + +### As a standalone tool from crates.io + +To install Viceroy as a standalone tool, you'll need to first [install Rust](https://www.rust-lang.org/tools/install) if you haven't already. Then run `cargo install viceroy`, which will download and build the latest Viceroy release. -## Usage +## Usage as a standalone tool + +**NOTE**: the Viceroy standalone CLI has a somewhat different interface from that +of [the Fastly CLI][cli]. Command-line options below describe the standalone +Viceroy interface. After installation, the `viceroy` command should be available on your path. The only required argument is the path to a compiled `.wasm` blob, which can be