280 lines
6.3 KiB
Markdown
280 lines
6.3 KiB
Markdown
# Servme
|
|
|
|
Un framework web HTTP de alto rendimiento escrito en Rust, construido sobre [Hyper](https://hyper.rs/).
|
|
|
|
## Primeros pasos
|
|
|
|
### Instalación
|
|
|
|
Añade `servme` a tu `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
servme = "0.1"
|
|
tokio = { version = "1", features = ["full"] }
|
|
```
|
|
|
|
### Tu primer servidor
|
|
|
|
```rust
|
|
use http_body_util::Full;
|
|
use hyper::{body::Bytes, Request, Response};
|
|
use servme::{Responder, Server, ServerError};
|
|
|
|
#[tokio::main]
|
|
async fn main() {
|
|
Server::builder()
|
|
.address("127.0.0.1", 8080)
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
}
|
|
|
|
async fn handler(req: Request<hyper::body::Incoming>) -> Result<Response<Full<Bytes>>, ServerError> {
|
|
Responder::ok(format!("Hola! Path: {}", req.uri()))
|
|
}
|
|
```
|
|
|
|
> **Para usuarios nuevos**: Ejecuta `cargo run` y visita `http://127.0.0.1:8080` en tu navegador.
|
|
|
|
---
|
|
|
|
## Conceptos básicos
|
|
|
|
### El Handler
|
|
|
|
El handler es una función asíncrona que recibe un `Request` y retorna una `Response`:
|
|
|
|
```rust
|
|
use http_body_util::Full;
|
|
use hyper::{body::Bytes, Request, Response};
|
|
|
|
async fn handler(req: Request<hyper::body::Incoming>) -> Result<Response<Full<Bytes>>, ServerError> {
|
|
// Tu lógica aquí
|
|
Responder::ok("Respuesta")
|
|
}
|
|
```
|
|
|
|
### Responder
|
|
|
|
`Responder` proporciona métodos auxiliares para crear respuestas HTTP comunes:
|
|
|
|
```rust
|
|
use servme::Responder;
|
|
|
|
// Respuestas de éxito
|
|
Responder::ok("Mensaje")?; // 200 OK
|
|
Responder::html("<h1>Título</h1>")?; // 200 con Content-Type: text/html
|
|
Responder::json(&datos)?; // 200 con Content-Type: application/json
|
|
Responder::redirect("/nueva-ruta")?; // 302 Redirect
|
|
Responder::no_content()?; // 204 No Content
|
|
|
|
// Respuestas de error
|
|
Responder::not_found()?; // 404
|
|
Responder::unauthorized()?; // 401
|
|
Responder::forbidden()?; // 403
|
|
Responder::bad_request("Datos inválidos")?; // 400
|
|
Responder::internal_error("Algo salió mal")?; // 500
|
|
```
|
|
|
|
### Extraer datos del Request
|
|
|
|
```rust
|
|
use servme::Requester;
|
|
|
|
// Extraer body JSON
|
|
let data: MyStruct = Requester::extract_body(req).await?;
|
|
|
|
// Extraer como texto
|
|
let body_str: String = Requester::extract_body_str(req).await?;
|
|
|
|
// Extraer como bytes (más eficiente)
|
|
let body_bytes: Bytes = Requester::extract_body_bytes(req).await?;
|
|
|
|
// Extraer parámetros de URL
|
|
let url = UrlExtract::new(req.uri());
|
|
let name = url.param_str("nombre"); // ?nombre=Juan
|
|
let age: Option<i64> = url.param_i64("edad"); // ?edad=25
|
|
```
|
|
|
|
---
|
|
|
|
## Middleware
|
|
|
|
Los middleware se ejecutan antes del handler y pueden authnticar, filtrar o modificar requests.
|
|
|
|
### API Key
|
|
|
|
```rust
|
|
use servme::{Server, ServerBuilder};
|
|
|
|
Server::builder()
|
|
.address("127.0.0.1", 8080)
|
|
.add_api_key_middleware("mi-clave-secreta")
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
```
|
|
|
|
Envía la clave en el header `X-API-Key`.
|
|
|
|
### JWT Authentication
|
|
|
|
```rust
|
|
use servme::{Server, ServerBuilder};
|
|
|
|
Server::builder()
|
|
.address("0.0.0.0", 8080)
|
|
.add_jwt_middleware(
|
|
rsa_public_key_pem, // Clave pública RSA en formato PEM
|
|
vec!["/health".to_string()], // Rutas públicas (sin auth)
|
|
)
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
```
|
|
|
|
El JWT se valida desde:
|
|
- Header `Authorization: Bearer <token>`
|
|
- Cookie `access_token`
|
|
|
|
### Filtrado por IP
|
|
|
|
```rust
|
|
use servme::ServerBuilder;
|
|
|
|
Server::builder()
|
|
.address("127.0.0.1", 8080)
|
|
.add_ip_filter_middleware(
|
|
vec!["192.168.1.100".to_string(), "10.0.0.1".to_string()],
|
|
true, // allow_private: también permitir IPs privadas (192.168.x.x, 10.x.x.x)
|
|
)
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
```
|
|
|
|
### Múltiples middlewares
|
|
|
|
```rust
|
|
Server::builder()
|
|
.address("0.0.0.0", 8080)
|
|
.add_ip_filter_middleware(vec![], true) // Permitir todas las IPs privadas
|
|
.add_jwt_middleware(pub_key, vec!["/static".to_string(), "/health".to_string()])
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
```
|
|
|
|
---
|
|
|
|
## Estado compartido
|
|
|
|
Puedes compartir datos entre requests usando `.data()`:
|
|
|
|
```rust
|
|
use std::sync::Arc;
|
|
|
|
#[derive(Clone)]
|
|
struct AppState {
|
|
db: Database,
|
|
}
|
|
|
|
Server::builder()
|
|
.address("127.0.0.1", 8080)
|
|
.data(AppState { db: Database::new() })
|
|
.build()
|
|
.run(|req| async move {
|
|
// Accede al estado desde las extensions del request
|
|
let state = req.extensions().get::<Arc<AppState>>().unwrap();
|
|
// Usa state.db...
|
|
Responder::ok("ok")
|
|
})
|
|
.await;
|
|
```
|
|
|
|
---
|
|
|
|
## Estructura del proyecto
|
|
|
|
```
|
|
src/
|
|
├── lib.rs # Exports públicos
|
|
├── main.rs # Binario de ejemplo
|
|
├── builder.rs # ServerBuilder - configuración del servidor
|
|
├── config.rs # ServerConfig - estructura de configuración
|
|
├── server.rs # Servidor HTTP con graceful shutdown
|
|
├── error.rs # ServerError - tipos de errores
|
|
├── constants.rs # Constantes del framework
|
|
├── responder.rs # Helpers para construir respuestas
|
|
├── requester.rs # Helpers para extraer datos del request
|
|
├── url_extract.rs # Parsing de URLs y query params
|
|
└── middleware/
|
|
├── mod.rs # Traits y tipos comunes
|
|
├── api_key.rs # Autenticación por API Key
|
|
├── jwt.rs # Autenticación JWT (RS256)
|
|
├── ip_filter.rs # Filtrado por dirección IP
|
|
└── auth_types.rs # Tipos para autenticación (Claims)
|
|
```
|
|
|
|
---
|
|
|
|
## Construcción y testing
|
|
|
|
```bash
|
|
# Compilar
|
|
cargo build
|
|
|
|
# Ejecutar tests
|
|
cargo test
|
|
|
|
# Ejecutar con logs de debug
|
|
RUST_LOG=debug cargo run
|
|
|
|
# Ver documentation
|
|
cargo doc --open
|
|
```
|
|
|
|
---
|
|
|
|
## Errores comunes
|
|
|
|
### "Failed to bind to address"
|
|
|
|
El puerto está en uso. Prueba con otro puerto:
|
|
|
|
```rust
|
|
Server::builder()
|
|
.address("127.0.0.1", 8081) // Cambia el puerto
|
|
.build()
|
|
.run(handler)
|
|
.await;
|
|
```
|
|
|
|
### "JWT validation failed"
|
|
|
|
- Verifica que la clave pública RSA sea válida
|
|
- Asegúrate de que el token no esté expirado (`exp` claim)
|
|
- El token debe contener el claim `sub` (subject)
|
|
|
|
---
|
|
|
|
## Constantes útiles
|
|
|
|
```rust
|
|
use servme::{
|
|
DEFAULT_HOST, // "127.0.0.1"
|
|
DEFAULT_PORT, // 8080
|
|
JWT_COOKIE_NAME, // "access_token"
|
|
BEARER_PREFIX, // "Bearer "
|
|
MAX_ALLOWED_IPS, // 1000
|
|
};
|
|
|
|
use servme::constants::FILE_EXTENSIONS; // Extensiones de archivos estáticos
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT |