server

What is this?

Server API that runs on AWS ECS.

How can I get started?

source wallet/bin/activate-hermit to acivate the local environment, then cd into wallet/server and use just to build/test.

Quickstart:

1. just submodules to make sure submodules are up to date
2. just run-integration in terminal 1 to run docker containers (you need to have docker running) for dynamodb-local and jaeger, and to run local versions of f8e (the API server) and WSM.
3. just test in terminal 2 to run unit and integration tests

Some useful commands (do just to see them all):

Command	Description
just	List available recipes
just sidecars	Start sidecars (dynamodb, mysql, jaeger)
just submodules	Pull submodule dependencies
just build	Build all (inc. api, wsm, ...)
just test	Run all tests
just run	Start sidecars and run the server in debug mode
just fmt	Format and lint
just vscode	Opens VSCode in server
just stack-up	Deploys stack to AWS development environment
just run-integration	Runs the entire server cluster

Building MUSL binary on an M1 mac (if you ever need to)

We don't recommend doing this locally as we are using Docker to build the binaries that target MUSL on GHA. This is reserved for if you want to deploy the service locally from CDK on your computer.

# rust toolchain support for musl x86 linux, which is what you need to run on x86 lambda.
rustup target add x86_64-unknown-linux-musl
# install buildchain
brew tap messense/macos-cross-toolchains
brew install x86_64-unknown-linux-musl
# tell cargo where to find the right linker and gcc
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=x86_64-unknown-linux-musl-gcc
export CC_x86_64_unknown_linux_musl=x86_64-unknown-linux-musl-gcc
# build!
cargo build --release --target=x86_64-unknown-linux-musl

OpenAPI Docs & Swagger

How it works:

You're building a new endpoint?

1. Add the utoipa::path struct a top of the endpoint (this has the path, the request type, the input and the various response types including the objects)
2. Add your endpoint to the ApiDoc for the given crate (just add the endpoint to the list) as well as any dependent response types under Schemas

You're adding a new crate with new endpoints?

1. Do steps 1 & 2 above in your new crate
2. Implement impl From<RouteState> for SwaggerEndpoint for your new crate
3. Add your api doc to the main server file under server/src/api/server/src/lib.rs

Tracing

We run Jaeger on http://localhost:16686 to view local traces.

We run Datadog on https://go/w1datadog to view traces from deployed servers.

Debugging route handlers

If you’re having trouble debugging issues related to Handlers (the trait Handler<_, _, _> is not implemented), use #[debug_handler] to give you more visibility.

#[axum_macros::debug_handler(state = crate::routes::axum::ServerState)] // add this
pub async fn handler(
    Path(wallet_id): Path<String>,
    State(something): State<Something>,
    Json(request): Json<Request>,
) -> Result<Json<Response>, ApiError> {
// ...
}

Testing

If you're having trouble running integration tests, for example with just test, make sure the server cluster is running, for example with just run-integration.

GitHub CLI

Some scripts, such as just stack-up, require a GitHub CLI login: gh auth login.