188 lines
6.9 KiB
Markdown
188 lines
6.9 KiB
Markdown
<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.
|