# Message Construction

## Overview
Message Construction patterns define what goes inside a message -- its intent, structure, metadata, and lifecycle. A well-constructed message is self-describing, carries the right amount of data, and enables the messaging system to route, correlate, and expire it correctly. Hohpe & Woolf identify patterns that address the intent of a message, how to correlate requests with replies, and how to manage message lifecycles.

## Patterns

### Command Message
Encodes an instruction to perform an action. Sent to a specific receiver on a Point-to-Point Channel.

```json
{
  "messageType": "command",
  "command": "PlaceOrder",
  "messageId": "cmd-8a3f-4b2c",
  "timestamp": "2025-01-15T10:30:00Z",
  "body": {
    "customerId": "cust-001",
    "items": [
      { "sku": "WIDGET-42", "quantity": 3 }
    ],
    "shippingAddress": "123 Main St"
  }
}
```

**When to use:** Invoking a specific action on a specific system -- order placement, account creation, state mutations.

### Document Message
Carries data without prescribing what the receiver should do with it. The sender transfers information; the receiver decides the action.

```json
{
  "messageType": "document",
  "documentType": "CustomerProfile",
  "messageId": "doc-9c4e-7d1a",
  "timestamp": "2025-01-15T10:31:00Z",
  "body": {
    "customerId": "cust-001",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tier": "gold",
    "lifetimeValue": 12500.00
  }
}
```

**When to use:** Data synchronisation, reporting feeds, transferring reference data between systems.

### Event Message
Notifies subscribers that something has happened. The sender does not dictate what receivers should do.

```json
{
  "messageType": "event",
  "eventType": "OrderPlaced",
  "messageId": "evt-2b7d-9e4f",
  "timestamp": "2025-01-15T10:32:00Z",
  "body": {
    "orderId": "order-5678",
    "customerId": "cust-001",
    "totalAmount": 149.97,
    "placedAt": "2025-01-15T10:30:00Z"
  }
}
```

**When to use:** Decoupled notification -- order placed, payment received, user registered. Publish on a Pub-Sub Channel.

### Request-Reply
A two-message exchange: the requestor sends a request and waits for a reply on a dedicated reply channel.

```json
// Request
{
  "messageType": "request",
  "messageId": "req-3c8a-1f2e",
  "replyTo": "channel://inventory-replies",
  "timestamp": "2025-01-15T10:33:00Z",
  "body": {
    "query": "CheckStock",
    "sku": "WIDGET-42"
  }
}

// Reply
{
  "messageType": "reply",
  "messageId": "rpl-7d4b-5a3c",
  "correlationId": "req-3c8a-1f2e",
  "timestamp": "2025-01-15T10:33:02Z",
  "body": {
    "sku": "WIDGET-42",
    "availableQuantity": 150,
    "warehouse": "US-EAST"
  }
}
```

**When to use:** When the sender needs a response but still wants temporal decoupling -- stock checks, credit approvals, price lookups.

### Return Address
Embeds the reply channel address in the request message so the receiver knows where to send the reply.

```json
{
  "messageId": "req-4a9b-2c1d",
  "replyTo": "channel://order-service/replies",
  "body": { "query": "GetOrderStatus", "orderId": "order-5678" }
}
```

**When to use:** Any Request-Reply scenario. Essential when multiple requestors share the same request channel.

### Correlation Identifier
A unique identifier placed in the reply message that references the original request, allowing the requestor to match replies to their requests.

```json
// Request (contains messageId)
{
  "messageId": "req-5b0c-3d2e",
  "replyTo": "channel://replies",
  "body": { "action": "ValidateAddress", "address": "123 Main St" }
}

// Reply (correlationId matches the request's messageId)
{
  "messageId": "rpl-8e1f-6a4b",
  "correlationId": "req-5b0c-3d2e",
  "body": { "valid": true, "normalised": "123 Main Street, Suite 100" }
}
```

**When to use:** Always use with Request-Reply. Critical when a requestor has multiple outstanding requests.

### Message Sequence
Marks messages as part of an ordered series when a large dataset must be split across multiple messages.

```json
{
  "messageId": "seq-6c1d-4e3f",
  "sequenceId": "batch-2025-01-15",
  "sequencePosition": 2,
  "sequenceSize": 5,
  "isLast": false,
  "body": {
    "records": [
      { "id": "rec-101", "value": "..." },
      { "id": "rec-102", "value": "..." }
    ]
  }
}
```

**When to use:** Transferring large datasets that exceed message size limits, ordered batch processing, streaming results.

### Message Expiration
Sets a time-to-live (TTL) on a message so it is discarded if not consumed before the deadline.

```json
{
  "messageId": "exp-7d2e-5f4a",
  "timestamp": "2025-01-15T10:30:00Z",
  "expiration": "2025-01-15T10:35:00Z",
  "body": {
    "type": "FlashSalePrice",
    "sku": "WIDGET-42",
    "price": 9.99
  }
}
```

**When to use:** Time-sensitive data (price quotes, session tokens, flash sales), preventing stale commands from executing.

### Format Indicator
Embeds version or format metadata in the message so consumers can handle multiple message schema versions.

```json
{
  "messageId": "fmt-8e3f-6a5b",
  "schemaVersion": "2.1",
  "contentType": "application/vnd.mycompany.order.v2+json",
  "body": {
    "orderId": "order-5678",
    "lineItems": [
      { "sku": "WIDGET-42", "qty": 3, "unitPrice": 49.99 }
    ]
  }
}
```

**When to use:** Schema evolution, multi-version consumers, gradual migration between message formats.

## Message Anatomy Reference

```json
{
  "messageId": "unique-id",
  "correlationId": "original-request-id",
  "causationId": "immediate-cause-message-id",
  "messageType": "command | event | document | request | reply",
  "schemaVersion": "1.0",
  "contentType": "application/json",
  "timestamp": "2025-01-15T10:30:00Z",
  "expiration": "2025-01-15T11:30:00Z",
  "replyTo": "channel://replies",
  "sequenceId": "batch-id",
  "sequencePosition": 1,
  "sequenceSize": 10,
  "headers": {
    "source": "order-service",
    "tenantId": "tenant-42"
  },
  "body": { }
}
```

## Choosing the Right Message Type

| Intent | Pattern |
|--------|---------|
| Tell a system to do something | Command Message |
| Transfer data without prescribing action | Document Message |
| Announce something happened | Event Message |
| Ask a question and wait for an answer | Request-Reply |
| Match a reply to its request | Correlation Identifier + Return Address |
| Send large data across multiple messages | Message Sequence |
| Prevent stale messages from being processed | Message Expiration |
| Support multiple schema versions | Format Indicator |

## Best Practices
- Give every message a unique `messageId` -- it is the foundation of idempotency, deduplication, and correlation.
- Prefer Event Messages for cross-service communication; they create the loosest coupling.
- Use Command Messages only when you intend exactly one receiver to act.
- Always include a `correlationId` in replies so requestors can match responses.
- Set `expiration` on time-sensitive messages rather than relying on consumers to check timestamps.
- Version your message schemas from day one using Format Indicator; schema evolution is inevitable.
- Keep message bodies lean -- carry references (IDs, URIs) rather than full object graphs when possible.
- Include `timestamp` and `source` in every message for observability and debugging.