diff --git a/src/lib.rs b/src/lib.rs index 0818be6..e2d3975 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -94,6 +94,8 @@ pub mod locale; pub mod datetime; // Tipos y funciones esenciales para crear acciones, componentes, extensiones y temas. pub mod core; +// Respuestas a peticiones web en sus diferentes formatos. +pub mod response; // Gestión del servidor y servicios web. pub mod service; // Reúne acciones, componentes y temas listos para usar. diff --git a/src/prelude.rs b/src/prelude.rs index 11c785f..7baa687 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -34,6 +34,7 @@ pub use crate::locale::*; pub use crate::datetime::*; pub use crate::service; +pub use crate::service::HttpRequest; pub use crate::core::{AnyCast, AnyInfo, TypeInfo}; @@ -42,6 +43,8 @@ pub use crate::core::component::*; pub use crate::core::extension::*; pub use crate::core::theme::*; +pub use crate::response::{redirect::*, ResponseError}; + pub use crate::base::action; pub use crate::base::component::*; pub use crate::base::theme; diff --git a/src/response.rs b/src/response.rs new file mode 100644 index 0000000..cf18377 --- /dev/null +++ b/src/response.rs @@ -0,0 +1,5 @@ +//! Respuestas a las peticiones web en sus diferentes formatos. + +pub use actix_web::ResponseError; + +pub mod redirect; diff --git a/src/response/redirect.rs b/src/response/redirect.rs new file mode 100644 index 0000000..bb3020d --- /dev/null +++ b/src/response/redirect.rs @@ -0,0 +1,98 @@ +//! Realiza redirecciones HTTP. +//! +//! **La redirección de URL** (o *URL forwarding*) es una técnica que permite asignar más de una +//! dirección a un mismo recurso web. HTTP define respuestas ***HTTP redirect*** para ello (ver +//! *[Redirections in HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections)*). +//! +//! Existen varios tipos de redirección, agrupados en tres grandes categorías: +//! +//! - **Redirecciones permanentes**. Se usan cuando el cambio de ubicación es definitivo. Indican +//! que la URL original ya no debe emplearse y que ha sido sustituida por la nueva. Los robots de +//! los buscadores, lectores RSS y otros *crawlers* suelen actualizar sus índices con la nueva +//! dirección. +//! +//! - **Redirecciones temporales**. Se aplican cuando el recurso no puede servirse desde su +//! ubicación canónica pero sí desde otra provisional. En este caso los buscadores **no** deben +//! memorizar la URL alternativa. También son útiles para mostrar páginas de progreso al crear, +//! actualizar o eliminar recursos. +//! +//! - **Respuestas especiales**. + +use crate::service::HttpResponse; + +/// Funciones predefinidas para generar respuestas HTTP de redirección. +/// +/// Ofrece atajos para construir respuestas con el código de estado apropiado, añade la cabecera +/// `Location` y la cierra con `.finish()`, evitando repetir la misma secuencia en cada controlador. +pub struct Redirect; + +impl Redirect { + /// Redirección **permanente**. Código de estado **301**. El método GET se conserva tal cual. + /// Otros métodos pueden degradarse a GET. Es una redirección típica para la reorganización de + /// un sitio o aplicación web. + /// + /// Emplear cuando un recurso se ha movido de forma definitiva y la URL antigua debe dejar de + /// usarse. + #[must_use] + pub fn moved(redirect_to_url: &str) -> HttpResponse { + HttpResponse::MovedPermanently() + .append_header(("Location", redirect_to_url)) + .finish() + } + + /// Redirección **permanente**. Código de estado **308**. Mantiene método y cuerpo sin cambios. + /// + /// Indicada para reorganizaciones de un sitio o aplicación web en las que también existen + /// métodos distintos de GET (POST, PUT, …) que no deben degradarse a GET. + #[must_use] + pub fn permanent(redirect_to_url: &str) -> HttpResponse { + HttpResponse::PermanentRedirect() + .append_header(("Location", redirect_to_url)) + .finish() + } + + /// Redirección **temporal**. Código de estado **302**. El método GET (y normalmente HEAD) se + /// mantiene tal cual. Otros métodos pueden degradarse a GET. + /// + /// Útil cuando un recurso está fuera de servicio de forma imprevista (mantenimiento breve, + /// sobrecarga, …). + #[must_use] + pub fn found(redirect_to_url: &str) -> HttpResponse { + HttpResponse::Found() + .append_header(("Location", redirect_to_url)) + .finish() + } + + /// Redirección **temporal**. Código de estado **303**. Método GET se mantiene tal cual. Los + /// demás métodos se cambian a GET (se pierde el cuerpo). + /// + /// Se usa típicamente tras un POST o PUT para aplicar el patrón *Post/Redirect/Get*, permite + /// recargar la página de resultados sin volver a ejecutar la operación. + #[must_use] + pub fn see_other(redirect_to_url: &str) -> HttpResponse { + HttpResponse::SeeOther() + .append_header(("Location", redirect_to_url)) + .finish() + } + + /// Redirección **temporal**. Código de estado **307**. Conserva método y cuerpo íntegros. + /// + /// Preferible a [`found`](Self::found) cuando el sitio expone operaciones diferentes de GET que + /// deben respetarse durante la redirección. + #[must_use] + pub fn temporary(redirect_to_url: &str) -> HttpResponse { + HttpResponse::TemporaryRedirect() + .append_header(("Location", redirect_to_url)) + .finish() + } + + /// Respuesta **especial**. Código de estado **304**. Se envía tras una petición condicional, + /// para indicar que la copia en caché sigue siendo válida y puede utilizarse, evitando + /// transferir de nuevo el recurso. + /// + /// No es una redirección, el cliente debe reutilizar su copia local. + #[must_use] + pub fn not_modified() -> HttpResponse { + HttpResponse::NotModified().finish() + } +} diff --git a/src/service.rs b/src/service.rs index 47e8422..cc32d56 100644 --- a/src/service.rs +++ b/src/service.rs @@ -6,7 +6,7 @@ pub use actix_web::dev::ServiceFactory as Factory; pub use actix_web::dev::ServiceRequest as Request; pub use actix_web::dev::ServiceResponse as Response; pub use actix_web::{http, rt, web}; -pub use actix_web::{App, Error, HttpRequest, HttpServer}; +pub use actix_web::{App, Error, HttpRequest, HttpResponse, HttpServer}; #[doc(hidden)] pub use actix_web::test;