# M4b task 02: the `gateway.sock` messages in `proto`

**Branch:** `m4b` (run `git switch m4b`; `git status --short` must be empty, otherwise stop)
**Commit subject:** `proto: gateway, the four messages between brokerd and gatewayd`

## Goal

One `gateway.sock` connection carries one pending approval from `brokerd` to `gatewayd`, and its
answer back (M4b spec, section 4). Every frame is a `proto` `Envelope`:

| # | From | `kind` | `final` | Body |
|---|---|---|---|---|
| 1 | `brokerd` | `approval_request` | true | `ApprovalRequest { approval: PendingApproval }` |
| 2 | `gatewayd` | `approval_posted` | false | `ApprovalPosted { posts: Vec<String> }` |
| 3 | `gatewayd` | `approval_reply` | true | `ApprovalReply { approval, approved, by, post, reason }` |
| 4 | `brokerd` | `approval_outcome` | true | `ApprovalOutcome { outcome: GatewayOutcome }` |

These are **our** format: unknown fields are errors everywhere.

## Files

- Copy: the skeleton `crates/proto/src/gateway.rs`, `crates/proto/tests/gateway_wire.rs`, and the
  eight fixtures `crates/proto/tests/fixtures/wire/gateway_*.json`
- Modify: `crates/proto/src/lib.rs`, `crates/proto/src/wire.rs`, `crates/brokerd/src/broker.rs`,
  `docs/implementer-log.md`

## The skeleton

Written: `MAX_REASON` (500), the four body types and `GatewayOutcome` with their serde attributes
(they are the wire format: do not change them). To fill: `is_mattermost_id` and
`ApprovalReply::check`, each with its steps above it.

## The changes, exactly

**`crates/proto/src/lib.rs`**: `pub mod gateway;` after `pub mod frame;`, and this re-export,
after the `pub use frame::…` line:

```rust
pub use gateway::{
    ApprovalOutcome, ApprovalPosted, ApprovalReply, ApprovalRequest, GatewayOutcome, MAX_REASON,
    is_mattermost_id,
};
```

**`crates/proto/src/wire.rs`**: four variants at the end of `enum Message`, after
`GrantsReport(GrantsReport),`:

```rust
    ApprovalRequest(ApprovalRequest),
    ApprovalPosted(ApprovalPosted),
    ApprovalReply(ApprovalReply),
    ApprovalOutcome(ApprovalOutcome),
```

and at the top, `use crate::gateway::{ApprovalOutcome, ApprovalPosted, ApprovalReply, ApprovalRequest};`.

**`crates/brokerd/src/broker.rs`**: `kind` must name every message. Add these four arms after
`Message::GrantsReport(_) => "grants_report",`, and change "all fourteen kinds" in its doc
comment to "all eighteen kinds":

```rust
        Message::ApprovalRequest(_) => "approval_request",
        Message::ApprovalPosted(_) => "approval_posted",
        Message::ApprovalReply(_) => "approval_reply",
        Message::ApprovalOutcome(_) => "approval_outcome",
```

## Steps

- [ ] **1. Copy.** `git switch m4b`, then
  `cp docs/plans/M4b/files/crates/proto/src/gateway.rs crates/proto/src/ && cp docs/plans/M4b/files/crates/proto/tests/gateway_wire.rs crates/proto/tests/ && cp docs/plans/M4b/files/crates/proto/tests/fixtures/wire/gateway_*.json crates/proto/tests/fixtures/wire/`.
- [ ] **2. Make the three edits above.** `cargo build --workspace` must succeed.
- [ ] **3. See it fail.** `cargo test -p proto --test gateway_wire`. Expected: 1 fails
  (`an_answer_is_checked`), 2 pass (the fixtures, since the types are given).
- [ ] **4. Fill `is_mattermost_id`, then `check`.** `cargo check -p proto` after each.
- [ ] **5. See it pass.** `cargo test -p proto --test gateway_wire`. Expected: 3 passed.
- [ ] **6. Run the gate.** `cargo fmt --all`, then `make gate`. Expected last line: `gate: ok`.
- [ ] **7. Log and commit.** `git add crates/proto crates/brokerd docs/implementer-log.md Cargo.lock && git commit`

## Done when

- `cargo test -p proto --test gateway_wire` passes; `make gate` prints `gate: ok`.

## Stop and report if

- A comment above a `todo!()` does not fit its function, or contradicts a test: quote it.