<picture>
    <source srcset="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_Solid_White.svg" media="(prefers-color-scheme: dark)">
    <img src="https://raw.githubusercontent.com/leptos-rs/leptos/main/docs/logos/Leptos_logo_RGB.svg" alt="Leptos Logo">
</picture>

# Leptos Axum Starter Template

This is a template for use with the [Leptos](https://github.com/leptos-rs/leptos) web framework and the [cargo-leptos](https://github.com/akesson/cargo-leptos) tool using [Axum](https://github.com/tokio-rs/axum).

## Creating your template repo

If you don't have `cargo-leptos` installed you can install it with

```bash
cargo install cargo-leptos --locked
```

Then run
```bash
cargo leptos new --git https://github.com/leptos-rs/start-axum
```

to generate a new project template.

```bash
cd code_submission
```

to go to your newly created project.
Feel free to explore the project structure, but the best place to start with your application code is in `src/app.rs`.
Additionally, Cargo.toml may need updating as new versions of the dependencies are released, especially if things are not working after a `cargo update`.

## Running your project

```bash
cargo leptos watch
```

Copy `dev.env` to `.env`, then replace the placeholder with a unique secret
before starting the server. The `.env` file is loaded automatically at startup
and is ignored by Git. Startup validates the required settings and stops with a
clear error if any are missing or malformed. `DEV_SECRET_KEY` authorizes server
status changes and submission-history access:

```powershell
Copy-Item dev.env .env
```

You can also provide `DEV_SECRET_KEY` through the process environment. Do not
commit secrets or expose them in client-side code.

Set `PROD=true` to make the server start in the live state. Truthy values are
`1`, `true`, `yes`, and `on` (case-insensitive); an absent or other value starts
the server offline.

Code 1 sends an SMS through TextBee when the server is live. Set
`TEXTBEE_API_KEY`, `RECIPIENT_SELF`, `RECIPIENT_1`, and `RECIPIENT_2` (each a
single E.164 number) in `.env`; `TEXTBEE_DEVICE_ID` is optional and selects a
specific paired device. When live, code 1 sends a notification to self, the
congratulations message to recipients 1 and 2, then `CHALLENGE_1_FIRST` to
recipient 1 and `CHALLENGE_1_SECOND` to recipient 2. The latter two are sent
literally as written. When offline, the planned messages are logged instead.
TextBee acceptance means a message was queued, not necessarily delivered.

Code 2 uses the former manual code value (`QJ4EAN`). Code values are case
insensitive. On successful submission, code 2 sends a notification to
`RECIPIENT_SELF` while the server is live (and logs the notification instead
while offline). The result page displays `NEXT_STEP_TEXT` from
`src/codes/code2.rs`; replace its TODO text with the next step when ready.

Code 5 uses the code value defined in `src/codes/code5.rs`. A successful
submission sends a notification to `RECIPIENT_SELF` while the server is live
(and logs the notification instead while offline), and displays the completion
message without providing a download.

The robot submits code 1 with `POST /event/buzz` and a JSON body containing
`delay_ms` (a non-negative integer) and `secret` (the value of `CODE1_SECRET`).
The server subtracts the target delay of 6430 ms from `delay_ms` to calculate
the signed buzz delta. Deltas outside the inclusive range -500 to +500 ms are
logged and ignored; the endpoint returns HTTP `200` and does not record the
submission or send/log the submission actions. Accepted submissions return
HTTP `202`. Correctly timed buzzes are only accepted between 11:00 AM and
1:30 PM, inclusive, in the `America/Chicago` timezone. Requests outside that
window are logged and return HTTP `200` without running submission actions.
Set `CODE1_SECRET` to a unique random secret of at least 32 bytes in
`.env`. For example, with the server running locally:

```sh
curl.exe -X POST http://127.0.0.1:3000/event/buzz -H "Content-Type: application/json" -d '{"delay_ms":6388,"secret":"<your CODE1_SECRET value>"}'
```

The server calculates `6388 - 6430 = -42` ms for the congratulations message.
A valid request returns HTTP `202`.

### Test code1 with Postman

Create a `POST` request to `http://127.0.0.1:3000/event/buzz`, select **Body >
raw > JSON**, and send:
```json
{
  "delay_ms": 6388,
  "secret": "<your CODE1_SECRET value>"
}
```

### Test code1 with Node.js

With the server running and `CODE1_SECRET` set in your shell, this sends a
single test event:

```javascript
async function main() {
  const delayMs = 6388;
  const secret = process.env.CODE1_SECRET;
  if (!secret) throw new Error("CODE1_SECRET is not set");

  const response = await fetch("http://127.0.0.1:3000/event/buzz", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ delay_ms: delayMs, secret }),
  });

  console.log(response.status, await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

When the server is live, a successful test event sends the configured TextBee
SMS to the configured recipients. When it is offline, it only logs the message.

## Installing Additional Tools

By default, `cargo-leptos` uses `nightly` Rust, `cargo-generate`, and `sass`. If you run into any trouble, you may need to install one or more of these tools.

1. `rustup toolchain install nightly --allow-downgrade` - make sure you have Rust nightly
2. `rustup target add wasm32-unknown-unknown` - add the ability to compile Rust to WebAssembly
3. `cargo install cargo-generate` - install `cargo-generate` binary (should be installed automatically in future)
4. `npm install -g sass` - install `dart-sass` (should be optional in future
5. Run `npm install` in end2end subdirectory before test

## Compiling for Release
```bash
cargo leptos build --release
```

Will generate your server binary in target/release and your site package in target/site

## Testing Your Project
```bash
cargo leptos end-to-end
```

```bash
cargo leptos end-to-end --release
```

Cargo-leptos uses Playwright as the end-to-end test tool.
Tests are located in end2end/tests directory.

## Executing a Server on a Remote Machine Without the Toolchain
After running a `cargo leptos build --release` the minimum files needed are:

1. The server binary located in `target/server/release`
2. The `site` directory and all files within located in `target/site`

Copy these files to your remote server. The directory structure should be:
```text
code_submission
site/
```
Set the following environment variables (updating for your project as needed):
```sh
export LEPTOS_OUTPUT_NAME="code_submission"
export LEPTOS_SITE_ROOT="site"
export LEPTOS_SITE_PKG_DIR="pkg"
export LEPTOS_SITE_ADDR="0.0.0.0:3000"
export LEPTOS_RELOAD_PORT="3001"
```
Finally, run the server binary.

## Licensing

This template itself is released under the Unlicense. You should replace the LICENSE for your own application with an appropriate license if you plan to release it publicly.