145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
# PureNotify Backend
|
|
|
|
This is the backend service for the PureNotify application, written in Rust. It's built to be a high-performance, reliable, and scalable foundation for sending notifications.
|
|
|
|
## 🚀 Features
|
|
|
|
- **Asynchronous:** Built with `tokio` and `axum` for non-blocking I/O and high concurrency.
|
|
- **Configurable:** Easily configure the application using environment variables.
|
|
- **Logging:** Integrated structured logging with `tracing` for better observability.
|
|
- **Graceful Shutdown:** Ensures the server shuts down cleanly without dropping active connections.
|
|
- **Health Check:** A dedicated endpoint to monitor the service's health.
|
|
|
|
## 🛠️ Technologies Used
|
|
|
|
- **[Rust](https://www.rust-lang.org/)**: The core programming language.
|
|
- **[Axum](https://github.com/tokio-rs/axum)**: A web application framework that focuses on ergonomics and modularity.
|
|
- **[Tokio](https://tokio.rs/)**: An asynchronous runtime for the Rust programming language.
|
|
- **[Serde](https://serde.rs/)**: A framework for serializing and deserializing Rust data structures efficiently.
|
|
- **[Dotenvy](https://github.com/dotenv-rs/dotenv)**: For loading environment variables from a `.env` file.
|
|
- **[Tracing](https://github.com/tokio-rs/tracing)**: A framework for instrumenting Rust programs to collect structured, event-based diagnostic information.
|
|
|
|
## ⚙️ Getting Started
|
|
|
|
Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.
|
|
|
|
### Prerequisites
|
|
|
|
You need to have the Rust toolchain installed on your system. If you don't have it, you can install it from [rustup.rs](https://rustup.rs/).
|
|
|
|
```sh
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
```
|
|
|
|
### Installation & Running
|
|
|
|
1. **Clone the repository:**
|
|
|
|
```sh
|
|
git clone https://github.com/your-username/purenotify_backend.git
|
|
cd purenotify_backend
|
|
```
|
|
|
|
2. **Create a `.env` file:**
|
|
Copy the example environment file to create your own local configuration.
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
You can modify the `.env` file to change the server's configuration.
|
|
|
|
3. **Build the project:**
|
|
|
|
```sh
|
|
cargo build
|
|
```
|
|
|
|
4. **Run the application:**
|
|
For development, you can run the project directly with `cargo run`:
|
|
```sh
|
|
cargo run
|
|
```
|
|
For a release build, run:
|
|
```sh
|
|
cargo run --release
|
|
```
|
|
|
|
The server will start, and you should see log output in your terminal indicating that it's running.
|
|
|
|
## 🔧 Configuration
|
|
|
|
The application is configured using environment variables. These can be set in a `.env` file in the project root or directly in your shell.
|
|
|
|
- `BIND_ADDRESS`: The IP address and port the server should listen on.
|
|
- **Default:** `127.0.0.1:3000`
|
|
- `RUST_LOG`: Controls the log level for the application.
|
|
- **Example:** `RUST_LOG=info,purenotify_backend=debug` will set the default log level to `info` and the log level for this crate to `debug`.
|
|
- **Default:** Reads from the environment; if not set, logging may be minimal.
|
|
|
|
## API Endpoints
|
|
|
|
Here are the available API endpoints for the service.
|
|
|
|
### Health Check
|
|
|
|
- **Endpoint:** `/health`
|
|
- **Method:** `GET`
|
|
- **Description:** Used to verify that the service is running and healthy.
|
|
- **Success Response:**
|
|
- **Code:** `200 OK`
|
|
- **Content:** `{"status": "ok"}`
|
|
|
|
#### Example Usage
|
|
|
|
You can use `curl` to check the health of the service:
|
|
|
|
```sh
|
|
curl http://127.0.0.1:3000/health
|
|
```
|
|
|
|
**Expected Output:**
|
|
|
|
```json
|
|
{
|
|
"status": "ok"
|
|
}
|
|
```
|
|
|
|
## 📂 Project Structure
|
|
|
|
The project follows a standard Rust project layout. The main application logic is located in the `src/` directory.
|
|
|
|
```
|
|
src/
|
|
├── main.rs # Application entry point, server setup
|
|
├── config.rs # Configuration management
|
|
├── handlers/ # Business logic for handling requests
|
|
│ └── health/
|
|
│ └── health.rs
|
|
├── routes/ # API route definitions
|
|
│ └── health/
|
|
│ └── health.rs
|
|
└── utils/ # Utility functions and shared modules
|
|
```
|
|
|
|
- `main.rs`: Initializes the server, logging, configuration, and wires up the routes.
|
|
- `config.rs`: Defines the `Config` struct and handles loading configuration from the environment.
|
|
- `handlers/`: Contains the core logic for each API endpoint. Each handler is responsible for processing a request and returning a response.
|
|
- `routes/`: Defines the Axum `Router` for different parts of the application. These modules map URL paths to their corresponding handlers.
|
|
- `utils/`: A place for helper functions or modules that are used across different parts of the application.
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
|
|
|
|
1. Fork the repository.
|
|
2. Create your feature branch (`git checkout -b feature/fooBar`).
|
|
3. Commit your changes (`git commit -am 'Add some fooBar'`).
|
|
4. Push to the branch (`git push origin feature/fooBar`).
|
|
5. Create a new Pull Request.
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
|