Axum Starter

This repository demonstrates a basic web server built using the Axum web framework in Rust. It includes routes with different functionalities, structured logging with tracing, and JSON handling.

Features

• Simple web server setup with tokio and axum
• Support for:
  • Basic routes
  • JSON requests and responses
  • Query and path parameter extraction
• Structured logging using tracing
• Configurable port using environment variables

---

Directory Structure

.
├── Cargo.lock       # Lock file for Rust dependencies
├── Cargo.toml       # Project dependencies and metadata
└── src
    └── main.rs     # Main application code

---

Requirements

• Rust (Ensure you have cargo installed)
• A terminal for running the application

---

Setup

1. Clone the repository:

   git clone https://github.com/nawodyaishan/axum-starter
   cd axum-starter

2. Build the project:

   cargo build

3. Run the server:

   cargo run

4. Access the application in your browser or via curl:

   • Root route: http://127.0.0.1:3000/
   • Hello World: http://127.0.0.1:3000/hello-world
   • Demo HTML: http://127.0.0.1:3000/demo.html
   • Demo JSON: http://127.0.0.1:3000/demo.json

---

Configuration

Change the Server Port

The server port can be configured using the PORT environment variable. By default, the application runs on port 3000.

To set a custom port:

• On Linux/macOS:

  PORT=8080 cargo run

• On Windows (Command Prompt):

  set PORT=8080 && cargo run

---

Routes and Handlers

Route	HTTP Method	Description
/	GET	Displays a welcome message
/hello-world	GET	Returns a Hello World message
/demo.html	GET	Serves a simple HTML response
/demo.json	GET	Returns a JSON response
/demo.json	PUT	Accepts and logs JSON data from the request
/items	GET	Displays query parameters
/items/:id	GET	Displays the provided path parameter

---

Example Usage

Accessing Routes

Root Route

curl http://127.0.0.1:3000/

Output:

Welcome to the Axum server!

JSON Endpoint

curl http://127.0.0.1:3000/demo.json

Output:

{
  "message": "This is a demo JSON response",
  "status": "success"
}

PUT JSON Data

curl -X PUT -H "Content-Type: application/json" -d '{"key":"value"}' http://127.0.0.1:3000/demo.json

Output:

Received JSON data: {"key":"value"}

Query Parameters

curl http://127.0.0.1:3000/items?key=value

Output:

Query parameters: {"key": "value"}

Path Parameters

curl http://127.0.0.1:3000/items/42

Output:

Item ID: 42

---

Logging

This project uses tracing for structured logging. Example log output:

INFO Server running at http://127.0.0.1:3000
INFO Accessed /hello-world route
INFO Received PUT request on /demo.json with data {"key":"value"}

Logs provide valuable debugging information and insights into request handling.

---

Dependencies

This project uses the following dependencies:

Dependency	Version	Functionality
axum	0.7	A web framework for building asynchronous applications in Rust. Used for creating routes, handling requests, and managing responses.
tokio	1	An asynchronous runtime for Rust. Provides the foundation for running async tasks, including the Axum server.
tracing	0.1.41	For structured and leveled logging. Used to provide detailed logs for debugging and monitoring.
tracing-subscriber	0.3.19	A library for managing and formatting logs from tracing. Enhances log output readability.
serde_json	1.0.133	A library for serializing and deserializing JSON. Used for handling JSON requests and responses in the application.
anyhow	1	Simplifies error handling in Rust with detailed context and backtraces. Used for managing errors in the project.

---