📘 add examples to `viceroy-lib` documentation

[cratelyn]

it would be nice if we provided some usage examples for viceroy_lib, to help people intending to use this library directly in their own testing infrastructure outside of the Fastly CLI.

i would particularly like to see examples showing how to start a service, and how to do this inside of a #[tokio::test] test case.

[GeeWee]

Yes I would absolutely love this as well - currently it's very hard to figure out how to make it work.

[GeeWee]

Some findings I've had to learn by myself.

• It should be documented what ExecuteCtx does, and how to use it
• Definitely emphasise we need to run in release mode. It specifies this, but I think it'd be good to hammer out exactly what happens where - creating ExectuteCtx::new() took 40 seconds on my machine, and I actually thought it was a deadlock multiple times.
• Document how to use this with tokio. Creating one ExecuteCtx per test is extremely slow (loading the .wasm file seems to take 1-3 seconds, whereas simply cloning an existing ExecuteCtx is almost instantaneous)

• Document what tokio test attribute to use. If you don't use the multi-threaded test scheduler you get some nasty errors when reusing cloned ExecuteCtx As an example

  lazy_static! {
  /// This is an example for using doc comment attributes
  static ref CONTEXT: viceroy_lib::ExecuteCtx = load_context();
  }
  
  pub fn load_context() -> viceroy_lib::ExecuteCtx {
      println!("WEEEEE");
      let path = Path::new("../target/wasm32-wasi/release/edge-api.wasi.wasm");
      if (!path.exists()) {
          panic!("Unable to find wasm file at path {path:?} - potentially the wasm binary has not been built");
      }
  
      // Load the wasm module into an execution context
      // todo this takes 40+ seconds if you're not running in release mode
  
      viceroy_lib::ExecuteCtx::new(&path).unwrap()
  }
  
  #[rstest]
  #[case("1")]
  #[case("2")]
  #[case("3")]
  #[case("4")]
  #[tokio::test(flavor = "multi_thread")]
  // #[tokio::test] <------------------------------ If you have a setup like this, and you use this test attribute, you will get errors
  async fn foo(#[case] case: &str) {
      // load WASM
  
      // create request
      let request = http::request::Builder::new()
          .method(Method::GET)
          .with_headers(&HashMap::from([(
              "Authorization".to_string(),
              "Bearer MY_LOCAL AUTH".to_string(),
          )]))
          .uri(format!("{}{}", BASE_URL, "/emission-factors"))
          .body(hyper::Body::empty())
          .unwrap();
  
      let res = CONTEXT
          .clone()
          .handle_request(request, "127.0.0.1".parse().unwrap())
          .await
          .unwrap();
  }

You'll get very unhelpful errors like this when not running multithreaded:

thread 'test_cases::tests::foo::case_13' panicked at 'guest worker finished without panicking: JoinError::Panic(Id(13), ...)', /Users/gustavwengel/.cargo/registry/src/github.com-1ecc6299db9ec823/viceroy-lib-0.2.15/src/execute.rs:201:18
stack backtrace:

This has been several hours of trial and error, and I think if it was documented better, this would be much more usable.

[caiges]

@GeeWee Do you have your tests in a different Cargo project with either the default host target or some other NON wasm32-wasi target? It looks like viceroy depends on hyper which isn't compatible with a wasm32-wasi target so having our tests live in the same codebase seems problematic if they're sharing the same .cargo/config. Feeling out for a good testing pattern.

[GeeWee]

I have them inside a different crate that does not directly depend on the "main" API package, but which does expect it's built before running.

( I also have not set wasm32-wasi target in my .cargo/config - fastly compute serve & build works fine without it)