Envelope Wrapper

1. Nombre del Patrón

• Nombre oficial: Envelope Wrapper
• Categoría: Message Transformation (Transformación de Mensajes)
• Traducción contextual: Envoltorio de Sobre

---

2. Resumen Ejecutivo

Envelope Wrapper es el patrón que permite envolver un mensaje de negocio dentro de una estructura de transporte externa (el "sobre") que contiene metadatos necesarios para el tránsito — seguridad, routing, correlación, trazabilidad — sin modificar el contenido original del mensaje. Al llegar al destino, el sobre se retira y el contenido original se entrega intacto al sistema consumidor.

El problema que resuelve es la tensión entre las necesidades de transporte y las necesidades de negocio: el mensaje de negocio no debería contaminarse con información de infraestructura (tokens de seguridad, headers de routing, metadatos de correlación), pero esa información es imprescindible durante el tránsito. Envelope Wrapper separa estas dos preocupaciones envolviéndolas en capas: el contenido de negocio viaja protegido dentro de un sobre de infraestructura.

Este patrón es omnipresente en la integración moderna. Cada request HTTP con headers y body implementa Envelope Wrapper. Cada mensaje SOAP con su header y body lo implementa. Cada CloudEvent que envuelve un evento de dominio en una estructura estandarizada lo implementa. La ubicuidad del patrón no lo hace trivial — las decisiones sobre qué va en el sobre y qué va en el contenido tienen impacto arquitectónico profundo.

---

3. Definición Detallada

Propósito

Envelope Wrapper establece una separación limpia entre el payload de negocio y los metadatos de transporte, permitiendo que cada uno evolucione de forma independiente. El sobre se gestiona por la capa de infraestructura; el contenido se gestiona por la capa de negocio.

Lógica Arquitectónica

En un sistema distribuido, un mensaje necesita llevar consigo información que va más allá de su contenido de negocio:

• Seguridad: tokens de autenticación, firmas digitales, certificados de cifrado.
• Routing: dirección de destino, routing keys, tipo de mensaje.
• Correlación: IDs de correlación, request-reply identifiers, trace IDs.
• Control de calidad de servicio: prioridad, TTL, garantía de entrega.
• Governance: timestamp de producción, origen, schema version.

Si toda esta información se mezcla con el payload de negocio, se produce un acoplamiento entre las preocupaciones de infraestructura y las de dominio. Un cambio en la política de seguridad requeriría modificar el formato del mensaje de negocio. Un cambio en la estrategia de routing contaminaría el esquema de datos.

Envelope Wrapper resuelve esto con un principio simple: el mensaje de negocio viaja dentro de un sobre que maneja la infraestructura. El productor crea el mensaje de negocio, la capa de integración lo envuelve en un sobre, el transporte utiliza el sobre para tomar decisiones, y el consumidor recibe el mensaje sin sobre.

Principio de Diseño Subyacente

El principio es separación de preocupaciones en capas (layered separation of concerns). Es el mismo principio que el modelo OSI: cada capa añade su propia "envoltura" (headers) al payload de la capa superior, y al llegar al destino, cada capa retira su envoltura. La capa de aplicación no necesita conocer los headers TCP; el mensaje de negocio no necesita conocer los headers de seguridad del sobre SOAP.

Problema Estructural que Resuelve

Sin Envelope Wrapper, las aplicaciones deben incluir metadatos de transporte dentro del propio mensaje de negocio. Esto produce:

• Acoplamiento entre dominio e infraestructura: el schema del mensaje incluye campos de seguridad, routing y control que no son parte del dominio.
• Fragilidad: un cambio en la política de seguridad (nuevo tipo de token, nuevo algoritmo de firma) requiere cambiar el schema de todos los mensajes.
• Incompatibilidad: diferentes canales de transporte requieren diferentes metadatos, forzando al productor a conocer y manejar cada canal.
• Contaminación del procesamiento: la lógica de negocio del consumidor debe parsear y ignorar campos de infraestructura que no le conciernen.

Contexto en el que Emerge

Envelope Wrapper emerge cuando un mensaje debe transitar por una infraestructura que necesita información adicional al contenido de negocio. Esto ocurre en prácticamente toda integración: mensajes que necesitan autenticación, routing, cifrado, trazabilidad o control de entrega.

Por Qué No Es Trivial

Aunque conceptualmente simple ("poner un sobre alrededor del mensaje"), las decisiones de diseño son complejas:

• Qué va en el sobre vs. qué va en el contenido: ¿el ID del cliente es metadata de routing (sobre) o dato de negocio (contenido)? ¿El timestamp es metadata de infraestructura o dato de auditoría?
• Cuántas capas de sobre: ¿un solo sobre o envolturas anidadas (sobre de seguridad dentro de sobre de transporte)?
• Quién envuelve y quién desenvuelve: ¿el productor? ¿Un middleware? ¿Un gateway?
• Formato del sobre: ¿propietario o estándar? ¿SOAP envelope? ¿CloudEvents? ¿HTTP headers?

Relación con Sistemas Distribuidos y Mensajería

En la teoría de sistemas distribuidos, Envelope Wrapper es análogo al concepto de protocol headers en la pila de protocolos de red. Cada capa del stack añade su header (su "sobre") y lo retira al otro extremo. En mensajería, el sobre permite que la infraestructura (brokers, routers, gateways) tome decisiones sobre el mensaje sin necesitar parsear el contenido de negocio.

---

4. Problema que Resuelve

El Problema Antes del Patrón

Sin Envelope Wrapper, cuando un sistema gubernamental necesita enviar datos tributarios a un sistema de validación externo:

• Los datos fiscales del contribuyente deben incluir tokens WS-Security dentro del propio XML de negocio.
• Si el canal requiere cifrado, los campos de cifrado se mezclan con los campos de datos fiscales.
• Si el routing requiere metadata (tipo de impuesto, jurisdicción), esos campos se añaden al schema tributario.
• El consumidor recibe un mensaje híbrido donde datos de negocio y de infraestructura están entremezclados, y debe extraer lo relevante descartando lo demás.

Síntomas del Problema

• Schemas de mensajes de negocio que incluyen campos de seguridad, routing o correlación que no son parte del dominio.
• Productores que deben modificar el formato de sus mensajes cada vez que cambia la infraestructura de transporte.
• Consumidores que deben parsear y descartar metadata de infraestructura antes de procesar el contenido de negocio.
• Imposibilidad de reutilizar el mismo mensaje de negocio a través de diferentes canales de transporte (cada canal exige sus propios metadatos mezclados en el mensaje).
• Dificultad para aplicar políticas de seguridad uniformes porque cada mensaje implementa la seguridad de forma diferente.

Impacto Operativo y Arquitectónico

Sin separación de sobre y contenido:

• La evolución de las políticas de seguridad requiere cambios en todos los schemas de mensajes.
• No se puede aplicar seguridad o routing de forma transparente en un gateway porque los metadatos están embebidos en el payload de cada tipo de mensaje.
• El testing de la lógica de negocio requiere incluir metadata de infraestructura en los datos de prueba.
• La migración de un protocolo de transporte a otro (por ejemplo, de SOAP a REST) requiere modificar todos los mensajes de negocio.

Riesgos Si No Se Implementa Correctamente

• Sobre insuficiente: omitir información necesaria en el sobre, forzando al router o gateway a parsear el payload de negocio para tomar decisiones de routing.
• Sobre excesivo: poner demasiada información en el sobre, convirtiendo el sobre en un segundo payload que hay que gestionar y evolucionar.
• Envoltura que no se desenvuelve: pasar el sobre completo al consumidor, forzándolo a ignorar o extraer el contenido manualmente.
• Sobres incompatibles: diferentes productores usando diferentes formatos de sobre para el mismo canal.

Ejemplos Reales

• Gobierno — declaraciones fiscales: una declaración de impuestos (XML con datos tributarios) se envuelve en un sobre SOAP con WS-Security (firma digital del contribuyente, token de autenticación del sistema emisor, timestamp con validez de 5 minutos). El gateway de la agencia tributaria valida el sobre, extrae la declaración y la pasa al sistema de procesamiento sin metadatos de seguridad.
• Banca — mensajería SWIFT: un mensaje de transferencia (MT103) viaja envuelto en un sobre SWIFT con headers de routing (BIC del emisor, BIC del receptor) y trailers de autenticación (MAC, CHK). La red SWIFT procesa el sobre; el banco receptor extrae el mensaje de transferencia.
• E-commerce — eventos CloudEvents: un evento order.created se envuelve en un sobre CloudEvents con specversion, type, source, id, time, datacontenttype. El broker usa el sobre para routing; el consumidor extrae el data con los detalles del pedido.

---

5. Contexto de Aplicación

Cuándo Usarlo

• Cuando el mensaje necesita transportar metadatos de infraestructura (seguridad, routing, correlación) que no son parte del dominio de negocio.
• Cuando el mismo mensaje de negocio debe poder transitar por diferentes canales de transporte con diferentes requisitos de metadata.
• Cuando se necesita aplicar políticas de seguridad, routing o transformación de forma transparente en intermediarios (gateways, brokers) sin parsear el contenido de negocio.
• Cuando se desea que el schema del mensaje de negocio sea independiente de la infraestructura de transporte.

Cuándo No Usarlo

• En comunicaciones internas punto-a-punto donde no hay intermediarios y no se necesita metadata de transporte separada.
• Cuando el overhead del sobre es desproporcionado respecto al tamaño del contenido (mensajes de telemetría ultra-pequeños con latencia crítica).
• Cuando el sobre y el contenido están tan acoplados que separarlos crea más complejidad que valor (un API REST simple donde los headers HTTP ya proporcionan el "sobre" nativo del protocolo).

Precondiciones

• Existe una definición clara de qué información es "de transporte" y qué información es "de negocio".
• Productores y consumidores comparten el acuerdo sobre el formato del sobre (estándar SOAP, CloudEvents, formato propietario).
• Existe un mecanismo de envoltura (wrapper) en el productor o en un intermediario, y un mecanismo de desenvoltura (unwrapper) en el consumidor o en un intermediario.

Restricciones

• El formato del sobre debe ser parseable por los intermediarios sin necesitar parsear el contenido.
• El sobre no debe modificar ni corromper el contenido durante el transporte.
• La envoltura y desenvoltura deben ser operaciones deterministas e idempotentes.

Dependencias

• Un formato de sobre definido y documentado (SOAP Envelope, CloudEvents, HTTP headers, formato propietario con schema).
• Intermediarios capaces de leer el sobre (gateways, routers, brokers).
• Lógica de wrapping y unwrapping implementada y testeada.

Supuestos Arquitectónicos

• La infraestructura de transporte necesita metadata que no es parte del dominio de negocio.
• Los intermediarios pueden tomar decisiones basándose solo en el sobre, sin inspeccionar el contenido.
• El contenido puede viajar opaco dentro del sobre sin perder su integridad.

Tipo de Sistemas Donde Aparece con Más Frecuencia

• Integraciones B2B y G2G (Government-to-Government) con SOAP y WS-Security.
• Arquitecturas event-driven con CloudEvents.
• APIs REST donde HTTP headers actúan como sobre y el body como contenido.
• Sistemas de mensajería donde message properties (headers) envuelven el payload.

---

6. Fuerzas Arquitectónicas

Acoplamiento vs. Flexibilidad

Envelope Wrapper reduce el acoplamiento entre el dominio de negocio y la infraestructura de transporte. El mensaje de negocio no sabe cómo viaja; el transporte no sabe qué transporta. Sin embargo, el formato del sobre se convierte en un punto de acoplamiento entre productores, intermediarios y consumidores: cambiar el formato del sobre requiere coordinación.

Simplicidad vs. Robustez

Un sobre simple (pocos campos de metadata) es fácil de gestionar pero puede ser insuficiente para escenarios complejos (seguridad multinivel, routing condicional). Un sobre robusto (muchos campos) cubre más escenarios pero es más complejo de implementar, validar y evolucionar.

Transparencia vs. Rendimiento

El sobre permite que los intermediarios tomen decisiones sin parsear el contenido (transparencia). Pero el sobre añade overhead: más bytes en el wire, más procesamiento para envolver y desenvolver. En mensajes pequeños y de alta frecuencia, el overhead del sobre puede ser significativo.

Seguridad vs. Complejidad

Envelope Wrapper es el mecanismo natural para implementar seguridad a nivel de transporte (firmas digitales, cifrado del contenido, tokens de autenticación). Pero cada capa de seguridad en el sobre añade complejidad en la generación, validación y troubleshooting.

Estandarización vs. Agilidad

Usar un formato de sobre estándar (SOAP, CloudEvents) facilita la interoperabilidad y el tooling. Pero adoptar un estándar puede ser constraining si las necesidades no encajan perfectamente. Un sobre propietario es más ágil pero pierde las ventajas de la estandarización.

Overhead de Envolvimiento vs. Aislamiento de Preocupaciones

Cada capa de sobre añade latencia de procesamiento. En un escenario con sobre de seguridad dentro de sobre de routing dentro de sobre de transporte, el overhead acumulado puede ser significativo. Pero sin esas capas, las preocupaciones se mezclan y el sistema se vuelve más difícil de mantener.

---

7. Estructura Conceptual del Patrón

Actores o Componentes Involucrados

1. Productor (Sender): genera el mensaje de negocio original.
2. Wrapper: envuelve el mensaje en un sobre con la metadata necesaria. Puede ser el propio productor, un middleware o un gateway.
3. Transporte / Intermediarios: procesan el sobre para tomar decisiones de routing, seguridad, logging sin tocar el contenido.
4. Unwrapper: retira el sobre y extrae el contenido original. Puede ser el propio consumidor, un middleware o un gateway.
5. Consumidor (Receiver): recibe y procesa el mensaje de negocio sin sobre.

Flujo Lógico

flowchart LR
    A([Productor]) --> B[Mensaje de negocio\ncontenido puro]
    B --> C[Wrapper añade sobre\nseguridad, routing, correlación]
    C --> D[Mensaje envuelto\nsobre + contenido]
    D --> E[Gateway valida\ntokens de seguridad]
    D --> F[Router lee routing key\npara dirigir mensaje]
    D --> G[Logger registra metadata\nsin inspeccionar contenido]
    E --> H[Unwrapper retira sobre\nextrae contenido]
    F --> H
    G --> H
    H --> I([Consumidor procesa\nmensaje de negocio limpio])

Responsabilidades

Componente	Responsabilidad
Productor	Crear el mensaje de negocio con el schema de dominio
Wrapper	Crear el sobre con metadata correcta, insertar el contenido sin modificarlo
Intermediarios	Leer y actuar sobre el sobre sin modificar el contenido
Unwrapper	Extraer el contenido del sobre, validar integridad
Consumidor	Procesar el contenido de negocio sin conocer el formato del sobre

Interacciones

• Productor → Wrapper: el productor entrega el contenido; el wrapper lo envuelve. Puede ser la misma aplicación (el productor sabe envolver) o un componente separado (un outbound gateway).
• Wrapper → Transporte: el mensaje envuelto se envía por el canal con el sobre como parte visible.
• Transporte → Unwrapper: el mensaje llega con el sobre intacto; el unwrapper lo procesa.
• Unwrapper → Consumidor: solo el contenido de negocio se entrega al consumidor.

Contratos Implícitos

• Formato del sobre: wrapper y unwrapper deben compartir el mismo formato de sobre.
• Integridad del contenido: el sobre no debe alterar el contenido durante wrapping/unwrapping.
• Metadata requerida: los intermediarios esperan ciertos campos en el sobre (por ejemplo, un gateway de seguridad espera un token; un router espera un routing key).

Decisiones de Diseño Clave

1. Formato del sobre: propietario vs. estándar (SOAP, CloudEvents, HTTP headers, AMQP properties).
2. Quién envuelve: ¿el productor, un middleware outbound, un gateway?
3. Quién desenvuelve: ¿el consumidor, un middleware inbound, un gateway?
4. Anidamiento: ¿un solo nivel de sobre o sobres anidados (sobre de seguridad dentro de sobre de routing)?
5. Contenido opaco vs. parseable: ¿el contenido viaja como blob opaco dentro del sobre o como estructura parseable?

---

8. Ejemplo Arquitectónico Detallado

Dominio: Gobierno — Transmisión Segura de Declaraciones Fiscales

Contexto del Negocio

La agencia tributaria de un país implementa un sistema de presentación electrónica de declaraciones fiscales. Los contribuyentes (personas físicas y empresas) presentan sus declaraciones a través de sistemas de terceros autorizados (software de contabilidad, gestorías digitales). Las declaraciones deben:

• Autenticarse con certificado digital del contribuyente.
• Cifrarse durante el tránsito para proteger datos fiscales sensibles (ingresos, deducciones, patrimonio).
• Incluir metadata de routing para dirigirlas al subsistema correcto (IRPF, IVA, Sociedades).
• Transportar un sello temporal legalmente vinculante.
• Llegar al sistema de procesamiento interno sin metadata de transporte, solo con los datos fiscales puros.

Necesidad de Integración

Miles de sistemas externos (software de contabilidad, ERPs, gestorías) deben enviar declaraciones fiscales al gateway de la agencia tributaria. Cada declaración contiene datos sensibles que deben protegerse en tránsito, pero el sistema interno de procesamiento fiscal no debe lidiar con cuestiones de seguridad ni transporte — solo con los datos tributarios.

Sistemas Involucrados

1. Software de Contabilidad (externo): genera la declaración fiscal en formato XML estándar.
2. Módulo de Firma y Envío (externo): envuelve la declaración en un sobre SOAP con WS-Security.
3. Gateway de la Agencia Tributaria: recibe los sobres, valida seguridad, desenvuelve y redirige.
4. Sistema de Procesamiento Fiscal (interno): procesa las declaraciones fiscales puras.
5. Módulo de Auditoría: almacena los sobres completos (con firma digital) para trazabilidad legal.

Restricciones Técnicas

• Las declaraciones deben firmarse con certificado X.509 del contribuyente.
• El contenido fiscal debe cifrarse con AES-256 y la clave cifrada con RSA-2048 del receptor.
• El sobre SOAP debe incluir un timestamp con validez de 5 minutos para prevenir replay attacks.
• El gateway debe validar la firma y descifrar el contenido sin pasar metadatos de seguridad al sistema de procesamiento.
• Los sobres completos deben archivarse por 10 años para auditoría legal.

Diseño del Sobre

<!-- Envelope (SOAP + WS-Security) -->
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <wsse:Security>
      <wsse:BinarySecurityToken>
        <!-- Certificado X.509 del contribuyente -->
      </wsse:BinarySecurityToken>
      <ds:Signature>
        <!-- Firma digital del contenido -->
      </ds:Signature>
      <wsu:Timestamp>
        <wsu:Created>2026-04-07T10:30:00Z</wsu:Created>
        <wsu:Expires>2026-04-07T10:35:00Z</wsu:Expires>
      </wsu:Timestamp>
    </wsse:Security>
    <routing:Metadata>
      <routing:TaxType>IRPF</routing:TaxType>
      <routing:FiscalYear>2025</routing:FiscalYear>
      <routing:Jurisdiction>ES-MD</routing:Jurisdiction>
    </routing:Metadata>
  </soap:Header>
  <soap:Body>
    <xenc:EncryptedData>
      <!-- Declaración fiscal cifrada (AES-256) -->
    </xenc:EncryptedData>
  </soap:Body>
</soap:Envelope>

Decisiones Arquitectónicas

1. Sobre SOAP + WS-Security: estándar maduro con tooling robusto para firma y cifrado XML.
2. Routing metadata en el header: el gateway lee el tipo de impuesto, año fiscal y jurisdicción del header SOAP sin descifrar el contenido.
3. Archivado del sobre completo: el sobre con la firma digital tiene valor legal como prueba de presentación.
4. Unwrapping en el gateway: el gateway valida la firma, descifra el contenido y envía solo el XML fiscal puro al sistema de procesamiento interno.

Riesgos y Mitigaciones

Riesgo	Mitigación
Replay attack con sobre capturado	Timestamp con ventana de 5 minutos + nonce
Firma inválida por certificado expirado	Validación OCSP/CRL en tiempo real en el gateway
Pérdida del sobre antes de archivar	Archivado transaccional antes de unwrapping
Overhead de cifrado/descifrado	HSM (Hardware Security Module) en el gateway
Evolución del formato fiscal interno	El sobre protege el contenido; el formato fiscal evoluciona independientemente

---

9. Desarrollo Paso a Paso del Ejemplo

Paso 1: Generación de la Declaración Fiscal

Un contribuyente (NIF: 12345678A) completa su declaración de IRPF del ejercicio 2025 usando un software de contabilidad autorizado. El software genera un XML con los datos fiscales:

<DeclaracionIRPF xmlns="urn:agencia-tributaria:irpf:v3">
  <Contribuyente>
    <NIF>12345678A</NIF>
    <Ejercicio>2025</Ejercicio>
  </Contribuyente>
  <RendimientosTrabajo>
    <Bruto>45000.00</Bruto>
    <Retencion>9450.00</Retencion>
  </RendimientosTrabajo>
  <Deducciones>
    <ViviendaHabitual>1200.00</ViviendaHabitual>
  </Deducciones>
  <ResultadoLiquidacion>
    <CuotaDiferencial>-850.00</CuotaDiferencial>
  </ResultadoLiquidacion>
</DeclaracionIRPF>

Este es el contenido puro de negocio. No contiene ningún metadato de seguridad, routing o transporte.

Paso 2: Wrapping — Envoltura en Sobre SOAP con WS-Security

El módulo de firma y envío del software:

1. Cifra el XML fiscal con AES-256. La clave AES se cifra con la clave pública RSA de la agencia tributaria.
2. Firma digitalmente el contenido cifrado con el certificado X.509 del contribuyente.
3. Construye el sobre SOAP: inserta el certificado, la firma, el timestamp y la metadata de routing en el <soap:Header>. Inserta el contenido cifrado en el <soap:Body>.
4. Envía el sobre SOAP completo al endpoint HTTPS del gateway de la agencia tributaria.

Paso 3: Procesamiento del Sobre en el Gateway

El gateway de la agencia tributaria recibe el sobre SOAP y ejecuta:

1. Valida timestamp: verifica que la hora de creación es reciente (dentro de 5 minutos). Si no, rechaza con error MessageExpired.
2. Valida certificado: verifica el certificado X.509 del contribuyente contra la CA (Certificate Authority) nacional. Consulta OCSP para verificar que no está revocado.
3. Valida firma digital: verifica que la firma corresponde al contenido y al certificado.
4. Archiva el sobre completo: almacena el sobre SOAP íntegro (con firma, certificado y contenido cifrado) en un storage de largo plazo para evidencia legal. Este archivo se retiene 10 años.
5. Lee routing metadata: extrae TaxType=IRPF, FiscalYear=2025, Jurisdiction=ES-MD del header SOAP.

Paso 4: Unwrapping — Desenvoltura

El gateway continúa:

1. Descifra el contenido: utiliza su clave privada RSA para descifrar la clave AES, y con ella descifra el XML fiscal.
2. Extrae el XML fiscal puro: el <DeclaracionIRPF> original, limpio de metadata de seguridad y transporte.
3. Añade metadata interna mínima: solo un receipt_id generado por el gateway para trazabilidad interna, como header del mensaje interno (no dentro del XML fiscal).

Paso 5: Entrega al Sistema de Procesamiento

El gateway envía el XML fiscal puro al sistema de procesamiento interno:

• El mensaje viaja por un canal interno (cola de Kafka o Azure Service Bus).
• El message header del canal contiene: receipt_id, tax_type=IRPF, fiscal_year=2025, jurisdiction=ES-MD.
• El message body contiene solo el XML fiscal sin ningún elemento de seguridad o transporte.

El sistema de procesamiento recibe un mensaje limpio de negocio. No sabe ni necesita saber que la declaración llegó en un sobre SOAP con WS-Security. Procesa los datos fiscales y calcula el resultado de la liquidación.

Paso 6: Respuesta con Sobre

El sistema de procesamiento genera un acuse de recibo (ReciboPresentacion). El gateway envuelve este recibo en un nuevo sobre SOAP con WS-Security (firmado con el certificado de la agencia) y lo devuelve al software del contribuyente. El ciclo de wrap → transmit → unwrap → process → wrap → transmit → unwrap se completa.

---

10. Diagrama Técnico del Patrón

Código Python con diagrams

GeneralAWSAzure

Ver / Copiar código de los diagramas

GeneralAWSAzure

from diagrams import Diagram, Cluster, Edge
from diagrams.onprem.compute import Server
from diagrams.onprem.security import Vault
from diagrams.onprem.queue import Kafka
from diagrams.generic.storage import Storage
from diagrams.onprem.network import Nginx

with Diagram("Envelope Wrapper - Declaraciones Fiscales", show=False, direction="LR"):

    with Cluster("Sistema Externo (Contribuyente)"):
        software = Server("Software\nContabilidad")
        wrapper = Server("Módulo Firma\ny Envío\n(Wrapper)")

    with Cluster("Gateway Agencia Tributaria"):
        gateway = Nginx("Gateway\nSOAP/WS-Security")
        hsm = Vault("HSM\n(Descifrado)")
        unwrapper = Server("Unwrapper\n(Extrae XML)")

    with Cluster("Archivado Legal"):
        archive = Storage("Archivo Sobres\n(10 años)")

    with Cluster("Sistema Interno"):
        queue = Kafka("Cola Interna\n(XML fiscal puro)")
        processor = Server("Procesamiento\nFiscal")

    with Cluster("Respuesta"):
        resp_wrapper = Server("Wrapper\nRespuesta")

    # Flujo de ida
    software >> Edge(label="XML fiscal\n(contenido puro)") >> wrapper
    wrapper >> Edge(label="SOAP + WS-Security\n(sobre completo)", color="darkred") >> gateway
    gateway >> Edge(label="Archiva sobre\ncompleto", style="dashed") >> archive
    gateway >> hsm
    hsm >> unwrapper
    unwrapper >> Edge(label="XML fiscal\n(sin sobre)", color="darkgreen") >> queue
    queue >> processor

    # Flujo de respuesta
    processor >> Edge(label="Recibo", style="dashed") >> resp_wrapper
    resp_wrapper >> Edge(label="SOAP + Firma\n(sobre respuesta)", style="dashed", color="darkred") >> gateway

from diagrams import Diagram, Cluster, Edge
from diagrams.aws.compute import Lambda
from diagrams.aws.integration import SQS
from diagrams.aws.network import APIGateway
from diagrams.aws.security import KMS
from diagrams.aws.storage import S3


with Diagram("Envelope Wrapper - Declaraciones Fiscales (AWS)", show=False, direction="LR"):

    with Cluster("Sistema Externo (Contribuyente)"):
        software = Lambda("Software\nContabilidad")
        wrapper = Lambda("Módulo Firma\ny Envío\n(Wrapper)")

    with Cluster("Gateway Agencia Tributaria"):
        gateway = APIGateway("API Gateway\nSOAP/WS-Security")
        hsm = KMS("AWS KMS\n(Descifrado)")
        unwrapper = Lambda("Unwrapper\n(Extrae XML)")

    with Cluster("Archivado Legal"):
        archive = S3("S3 Glacier\nArchivo Sobres\n(10 años)")

    with Cluster("Sistema Interno"):
        queue = SQS("SQS Cola Interna\n(XML fiscal puro)")
        processor = Lambda("Procesamiento\nFiscal")

    with Cluster("Respuesta"):
        resp_wrapper = Lambda("Wrapper\nRespuesta")

    # Flujo de ida
    software >> Edge(label="XML fiscal\n(contenido puro)") >> wrapper
    wrapper >> Edge(label="SOAP + WS-Security\n(sobre completo)", color="darkred") >> gateway
    gateway >> Edge(label="Archiva sobre\ncompleto", style="dashed") >> archive
    gateway >> hsm
    hsm >> unwrapper
    unwrapper >> Edge(label="XML fiscal\n(sin sobre)", color="darkgreen") >> queue
    queue >> processor

    # Flujo de respuesta
    processor >> Edge(label="Recibo", style="dashed") >> resp_wrapper
    resp_wrapper >> Edge(label="SOAP + Firma\n(sobre respuesta)", style="dashed", color="darkred") >> gateway

from diagrams import Diagram, Cluster, Edge
from diagrams.azure.security import KeyVaults
from diagrams.azure.compute import FunctionApps
from diagrams.azure.integration import ServiceBus, APIManagement
from diagrams.azure.storage import BlobStorage


with Diagram("Envelope Wrapper - Declaraciones Fiscales (Azure)", show=False, direction="LR"):

    with Cluster("Sistema Externo (Contribuyente)"):
        software = FunctionApps("Software\nContabilidad")
        wrapper = FunctionApps("Módulo Firma\ny Envío\n(Wrapper)")

    with Cluster("API Management (Inbound/Outbound Policies)"):
        gateway = APIManagement("API Management\nSOAP/WS-Security\n(Inbound Policy:\nvalidate-jwt,\nxml-to-json)")
        keyvault = KeyVaults("Azure Key Vault\n(Certificados\ny Descifrado)")
        unwrapper = FunctionApps("Unwrapper\n(Extrae XML\nvia APIM Policy)")

    with Cluster("Archivado Legal"):
        archive = BlobStorage("Blob Storage\n(Archivo Legal\n10 años, immutable)")

    with Cluster("Sistema Interno"):
        queue = ServiceBus("Service Bus Queue\n(XML fiscal puro)")
        processor = FunctionApps("Procesamiento\nFiscal")

    with Cluster("Respuesta"):
        resp_wrapper = FunctionApps("Wrapper\nRespuesta\n(Outbound Policy:\nxml-sign)")

    # Flujo de ida
    software >> Edge(label="XML fiscal\n(contenido puro)") >> wrapper
    wrapper >> Edge(label="SOAP + WS-Security\n(sobre completo)", color="darkred") >> gateway
    gateway >> Edge(label="Archiva sobre\ncompleto", style="dashed") >> archive
    gateway >> Edge(label="decrypt /\nvalidate cert") >> keyvault
    keyvault >> unwrapper
    unwrapper >> Edge(label="XML fiscal\n(sin sobre)", color="darkgreen") >> queue
    queue >> processor

    # Flujo de respuesta
    processor >> Edge(label="Recibo", style="dashed") >> resp_wrapper
    resp_wrapper >> Edge(label="SOAP + Firma\n(sobre respuesta)", style="dashed", color="darkred") >> gateway

Explicación del Diagrama

El diagrama muestra el flujo completo de envelope wrapping en el sistema de declaraciones fiscales:

1. El Software de Contabilidad genera el XML fiscal puro (contenido de negocio).
2. El Módulo de Firma y Envío actúa como Wrapper: envuelve el XML en un sobre SOAP con WS-Security (firma, cifrado, timestamp, routing).
3. El Gateway recibe el sobre, archiva el sobre completo para evidencia legal, y procede a validar y desenvolver.
4. El HSM maneja el descifrado de forma segura.
5. El Unwrapper extrae el XML fiscal puro, libre de metadata de seguridad y transporte.
6. El XML puro se envía a la Cola Interna y de ahí al Procesamiento Fiscal, que solo conoce datos de negocio.
7. La respuesta sigue el camino inverso: el recibo se envuelve en un nuevo sobre SOAP firmado.

Correspondencia Patrón ↔ Diagrama

Concepto del Patrón	Componente del Diagrama
Contenido de negocio	XML fiscal (DeclaracionIRPF)
Wrapper	Módulo de Firma y Envío
Sobre (Envelope)	SOAP + WS-Security (firma, cifrado, timestamp, routing)
Intermediario	Gateway de la Agencia Tributaria
Unwrapper	Componente Unwrapper en el gateway
Consumidor	Sistema de Procesamiento Fiscal
Archivado del sobre	Storage de archivo legal

---

11. Beneficios

Impacto Técnico

• Separación de preocupaciones: el mensaje de negocio y la metadata de transporte se gestionan independientemente. Un cambio en la política de seguridad (nuevo algoritmo de firma) no modifica el schema fiscal.
• Routing transparente: los intermediarios (gateways, routers) toman decisiones de routing leyendo el sobre sin parsear el contenido cifrado.
• Seguridad en capas: el sobre permite implementar firma, cifrado y autenticación sin contaminar el payload de negocio.
• Reutilización del contenido: el mismo XML fiscal puede enviarse por diferentes canales (SOAP, REST con CloudEvents, mensajería) cambiando solo el sobre.

Impacto Organizacional

• Autonomía de equipos: el equipo de infraestructura gestiona el formato del sobre; el equipo de dominio gestiona el formato del contenido. Cada uno evoluciona de forma independiente.
• Interoperabilidad: si el sobre sigue un estándar (SOAP, CloudEvents), cualquier sistema que implemente el estándar puede participar sin desarrollar integraciones propietarias.
• Compliance: el sobre proporciona un punto natural para implementar requisitos regulatorios (firma digital, cifrado, timestamps legales) sin modificar los sistemas de negocio.

Impacto Operacional

• Auditoría: archivar el sobre completo (con firma digital y timestamp) proporciona evidencia legal de la transmisión.
• Troubleshooting: los metadatos del sobre (timestamps, correlation IDs, routing keys) facilitan el rastreo de mensajes a través de la infraestructura.
• Evolución: migrar de un protocolo de transporte a otro (por ejemplo, de SOAP a CloudEvents) solo requiere cambiar los wrappers/unwrappers, no los sistemas de negocio.

Beneficios de Mantenibilidad y Evolución

• Versionado independiente: el formato del sobre puede versionarse separadamente del formato del contenido.
• Extensibilidad del sobre: añadir nuevos campos al sobre (por ejemplo, un nuevo header de tracing) no impacta el contenido de negocio.
• Testing simplificado: la lógica de negocio se testea con mensajes puros; la lógica de envolvimiento se testea por separado.

---

12. Desventajas y Riesgos

Complejidad Añadida

• Lógica de wrapping/unwrapping: hay que desarrollar, testear y mantener la lógica de envolver y desenvolver mensajes. En escenarios complejos (cifrado + firma + routing), esta lógica no es trivial.
• Overhead de procesamiento: envolver y desenvolver consume CPU (especialmente con cifrado y firma digital) y tiempo. En canales de alto throughput, esto puede ser significativo.
• Overhead de tamaño: el sobre añade bytes al mensaje. En SOAP con WS-Security, el overhead del sobre puede ser mayor que el contenido.

Riesgos de Mal Uso

• Sobre como canal de datos de negocio: poner datos de negocio en el sobre porque es "más fácil de acceder" desde los intermediarios. Esto rompe la separación de preocupaciones.
• Sobres anidados excesivos: múltiples capas de sobre (transporte → seguridad → routing → correlación) que hacen el procesamiento complejo y lento.
• Unwrapping incompleto: pasar al consumidor un mensaje parcialmente envuelto (con algunos headers de infraestructura aún presentes).

Sobreingeniería

• Implementar Envelope Wrapper con un formato propietario complejo cuando los headers nativos del protocolo de transporte (HTTP headers, AMQP message properties, Kafka headers) son suficientes.
• Crear múltiples capas de sobre cuando una sola capa con todos los metadatos sería suficiente.

Costos de Operación

• Gestión de certificados: si el sobre usa firma digital, los certificados deben gestionarse (emisión, renovación, revocación).
• Compatibilidad de versiones: si el formato del sobre evoluciona, los wrappers y unwrappers deben soportar múltiples versiones durante la transición.
• Debugging: un error en el wrapping puede corromper el sobre y causar rechazo en el gateway, con mensajes de error que apuntan al sobre, no al contenido.

Anti-Patterns Relacionados

• Fat Envelope: un sobre que contiene más metadata que contenido de negocio, indicando que la separación de preocupaciones no es correcta.
• Transparent Envelope: un sobre que no cifra ni protege el contenido, derrotando uno de los propósitos principales del patrón.
• Permanent Envelope: el sobre nunca se retira y el consumidor debe lidiar con él permanentemente.

---

13. Relación con Otros Patrones

Patrones Complementarios

• Content Enricher (este capítulo): a veces el Wrapper actúa como enricher, añadiendo metadata que no existía en el mensaje original.
• Content Filter (este capítulo): el Unwrapper actúa como filter, eliminando la metadata de transporte antes de entregar al consumidor.
• Message Translator (Capítulo 2): si el contenido además de desenvolverse necesita transformarse al formato del consumidor, Message Translator complementa al Unwrapper.

Patrones que Suelen Aparecer Antes o Después

• Antes: el mensaje de negocio se construye con patrones de construcción (Document Message, Command Message, Event Message).
• Después: el mensaje desenvuelto se procesa con patrones de routing (Content-Based Router) o transformación (Content Enricher, Content Filter).

Combinaciones Comunes

• Envelope Wrapper + Content-Based Router: el router lee el sobre para tomar decisiones de routing sin parsear el contenido.
• Envelope Wrapper + Claim Check: el sobre contiene una referencia (claim check) en lugar del contenido completo, combinando externalización con envoltura.
• Envelope Wrapper + Wire Tap: se intercepta el sobre para logging/auditoría antes de desenvolver.

Diferencias con Patrones Similares

• vs. Message Translator: Translator cambia el formato del contenido; Envelope Wrapper añade/retira una capa externa sin modificar el contenido.
• vs. Content Enricher: Enricher añade datos de negocio al mensaje; Envelope Wrapper añade metadata de infraestructura alrededor del mensaje.

Encaje en un Flujo Mayor de Integración

Envelope Wrapper típicamente es el primer paso al enviar un mensaje (wrap) y el último paso al recibirlo (unwrap). Opera en los bordes de la arquitectura — en los gateways de entrada/salida — protegiendo el tránsito entre dominios de seguridad diferentes.

---

14. Relevancia Actual del Patrón

Evaluación: Relevancia Alta

Argumentación

Envelope Wrapper es omnipresente en las arquitecturas modernas, aunque frecuentemente pasa desapercibido porque los frameworks lo implementan de forma transparente:

• HTTP headers + body: cada request HTTP implementa Envelope Wrapper. Los headers (Authorization, Content-Type, X-Correlation-ID, traceparent) son el sobre; el body es el contenido.
• CloudEvents: el estándar CloudEvents define explícitamente un sobre (specversion, type, source, id, time) que envuelve el campo data (el contenido de negocio).
• Kafka message properties: los headers de un mensaje Kafka (key, headers map, timestamp) son el sobre; el value es el contenido.
• AMQP message properties: en RabbitMQ/Azure Service Bus, las properties (message-id, correlation-id, content-type, reply-to) son el sobre; el body es el contenido.
• gRPC metadata: los metadatos de una llamada gRPC actúan como sobre del mensaje protobuf.

Cómo Se Implementa Hoy

Contexto	Sobre	Contenido
HTTP REST	Headers (Authorization, Content-Type, traceparent)	Body (JSON/XML)
CloudEvents	Atributos CloudEvents (specversion, type, source, id)	Campo data
Kafka	Message key + headers map + metadata	Message value
AMQP	Message properties + application-properties	Message body
gRPC	Metadata entries	Protobuf message
SOAP	SOAP Header (WS-Security, WS-Addressing)	SOAP Body

Qué Parte Sigue Siendo Esencial

• La separación sobre/contenido: es un principio permanente, independientemente de la tecnología.
• CloudEvents como sobre estándar: se está consolidando como el estándar de facto para eventos en arquitecturas cloud-native.
• Observability headers: traceparent, tracestate (W3C Trace Context) viajan en el sobre para distributed tracing sin contaminar el payload.
• Security tokens: JWT/OAuth2 tokens viajan en headers (sobre), no en el body.

---

15. Implementación en Arquitecturas Modernas

CloudEvents sobre HTTP

POST /events HTTP/1.1
Host: tax-gateway.gob.es
Content-Type: application/cloudevents+json
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

{
  "specversion": "1.0",
  "type": "gov.tax.declaration.submitted",
  "source": "/accounting-software/v3",
  "id": "decl-2026-04-07-a1b2c3",
  "time": "2026-04-07T10:30:00Z",
  "datacontenttype": "application/xml",
  "subject": "NIF:12345678A",
  "data_base64": "PERlY2xhcmFjaW9uSVJQRi4uLg=="
}

CloudEvents proporciona un sobre estandarizado. Los intermediarios (API gateways, event routers) procesan los atributos del sobre (type, source, subject) para routing y filtering sin decodificar el data.

Kafka con Headers

from confluent_kafka import Producer

producer = Producer({'bootstrap.servers': 'kafka:9092'})

headers = [
    ('ce_specversion', b'1.0'),
    ('ce_type', b'gov.tax.declaration.submitted'),
    ('ce_source', b'/accounting-software/v3'),
    ('ce_id', b'decl-2026-04-07-a1b2c3'),
    ('ce_time', b'2026-04-07T10:30:00Z'),
    ('traceparent', b'00-abcdef1234567890-fedcba0987654321-01'),
    ('authorization', b'Bearer eyJhbGciOiJSUzI1NiIs...')
]

producer.produce(
    topic='gov.tax.declarations',
    key=b'12345678A',
    value=declaracion_xml_bytes,  # Contenido puro
    headers=headers  # Sobre
)

Los Kafka headers actúan como sobre: los consumidores y stream processors pueden inspeccionar los headers para routing y filtering sin deserializar el value.

Azure Service Bus con Message Properties

var message = new ServiceBusMessage(declaracionXmlBytes)
{
    ContentType = "application/xml",
    Subject = "IRPF",
    CorrelationId = "decl-2026-04-07-a1b2c3",
    MessageId = Guid.NewGuid().ToString(),
    ApplicationProperties =
    {
        ["fiscal_year"] = "2025",
        ["jurisdiction"] = "ES-MD",
        ["nif"] = "12345678A",
        ["traceparent"] = "00-abcdef1234567890-fedcba0987654321-01"
    }
};

Azure Service Bus separa nativamente las properties (sobre) del body (contenido), permitiendo filtros SQL en subscriptions que operan sobre el sobre.

API Gateway como Unwrapper Automático

En arquitecturas modernas, el API Gateway (Kong, AWS API Gateway, Azure APIM) actúa como unwrapper automático: valida el token OAuth2 del header, extrae el trace context, y reenvía al servicio interno solo el body con headers internos limpios.

---

16. Consideraciones de Gobierno y Operación

Observabilidad

• Trace context en el sobre: propagar traceparent y tracestate (W3C Trace Context) en el sobre de cada mensaje para trazabilidad end-to-end.
• Logging del sobre: registrar los metadatos del sobre (type, source, id, time) en cada paso sin logear el contenido (que puede ser sensible).
• Métricas por tipo de sobre: medir throughput, latencia y errores por type y source del sobre.

Monitoreo

• Errores de validación de sobre: monitorear la tasa de sobres rechazados (firma inválida, timestamp expirado, campos faltantes) como indicador de problemas en productores.
• Latencia de wrapping/unwrapping: si el cifrado/descifrado del sobre causa latencia excesiva, puede necesitarse optimización (HSM, caching de sesiones TLS).
• Tamaño del sobre vs. contenido: monitorear la proporción de overhead del sobre respecto al contenido total.

Versionado

• Versionado del formato del sobre: definir una estrategia de evolución del sobre (nuevos campos opcionales, deprecated fields) que no rompa los intermediarios.
• Compatibilidad backward: los unwrappers deben manejar sobres de versiones anteriores durante períodos de transición.
• CloudEvents specversion: CloudEvents incluye specversion en el sobre para manejar evolución del formato.

Seguridad

• Firma digital del sobre: para integraciones B2B y G2G, la firma digital en el sobre proporciona no-repudio.
• Cifrado del contenido: el contenido puede cifrarse dentro del sobre (end-to-end encryption) mientras el sobre permanece legible para los intermediarios.
• Validación de tokens: los tokens de autenticación en el sobre deben validarse en el gateway antes de permitir el unwrapping.

Manejo de Errores

• Sobre inválido: rechazar con error específico que indique qué campo del sobre es incorrecto, sin revelar información del contenido.
• Contenido corrupto: si al desenvolver el contenido está corrupto (por ejemplo, descifrado fallido), archivarse el sobre completo para diagnóstico.
• Dead-lettering de sobres: los sobres que no pueden procesarse van a un dead-letter channel con el sobre intacto para análisis posterior.

Auditoría

• Retención de sobres: en escenarios regulados (gobierno, banca), archivar el sobre completo con firma digital como evidencia legal.
• Registro de wrapping/unwrapping: registrar quién envolvió, cuándo, con qué certificado; quién desenvolvió, cuándo, resultado de la validación.

---

17. Errores Comunes

Mezclar Datos de Negocio en el Sobre

Poner datos de negocio (por ejemplo, el monto de la declaración) en el sobre porque "es útil para el routing". Esto contamina el sobre con preocupaciones de dominio y crea acoplamiento. Si se necesita routing por datos de negocio, usar un campo de routing derivado (category, type), no el dato crudo.

No Definir Quién Desenvuelve

Asumir que "alguien" retirará el sobre. Sin un componente explícito de unwrapping, el consumidor recibe el sobre completo y debe parsear/ignorar la metadata de transporte. Esto vence el propósito del patrón.

Sobre Propietario Cuando Existe Estándar

Diseñar un formato de sobre propietario (campos custom, estructura ad-hoc) cuando CloudEvents, SOAP o los headers nativos del protocolo son suficientes. Los formatos estándar tienen tooling, documentación y interoperabilidad que un formato propietario no ofrece.

Ignorar el Overhead del Sobre en Mensajes Pequeños

En sistemas de telemetría IoT donde el payload es de 50 bytes, un sobre CloudEvents JSON puede añadir 200+ bytes. Para estos casos, considerar formatos binarios (CloudEvents en Protobuf, AMQP binary headers) o sobre implícito del protocolo.

No Archivar el Sobre Cuando Tiene Valor Legal

En integraciones reguladas, descartar el sobre después del unwrapping pierde la firma digital y el timestamp que tienen valor probatorio. Siempre archivar el sobre completo en escenarios con requisitos de auditoría o compliance.

Asumir que el Contenido No Necesita Protección Propia

Confiar solo en el cifrado del transporte (TLS) y no cifrar el contenido dentro del sobre. Si el mensaje atraviesa múltiples intermediarios, el contenido está expuesto en cada uno. El cifrado del contenido dentro del sobre (end-to-end encryption) protege contra intermediarios comprometidos.

---

18. Conclusión Técnica

Envelope Wrapper es un patrón estructural que separa las preocupaciones de transporte (seguridad, routing, correlación, trazabilidad) del contenido de negocio. Aunque conceptualmente simple, su correcta implementación requiere decisiones deliberadas sobre formato del sobre, punto de wrapping/unwrapping, y gestión del ciclo de vida del sobre.

Cuándo aporta valor: en toda integración donde el mensaje necesita metadatos de transporte separados del contenido de negocio. Es especialmente valioso en integraciones B2B, G2G y cross-domain donde la seguridad y la trazabilidad son críticas.

Cuándo evita problemas importantes: cuando se necesita evolucionar las políticas de seguridad o la infraestructura de transporte sin impactar los schemas de negocio. Cuando se necesita aplicar políticas uniformes (seguridad, routing, logging) en un gateway sin parsear contenidos heterogéneos.

Cuándo no conviene adoptarlo de forma explícita: cuando los headers nativos del protocolo (HTTP headers, Kafka headers, AMQP properties) ya proporcionan un sobre suficiente y no se necesita un formato de sobre adicional. En estos casos, el patrón sigue existiendo implícitamente — simplemente no requiere implementación adicional.

Recomendación para arquitectos: reconozca que Envelope Wrapper está presente en toda integración, implícita o explícitamente. Use formatos de sobre estándar (CloudEvents, HTTP headers, AMQP properties) siempre que sea posible. Defina explícitamente qué va en el sobre y qué va en el contenido. Cuando el sobre tiene valor legal o de auditoría, archívelo antes de desenvolver. Y diseñe el wrapping/unwrapping como componentes explícitos y testeables, no como lógica dispersa en el código de negocio.