Accept the message the protocol calls for, then continue.

Only compiles at Recv(message, then). The message has already arrived and been narrowed by the case in the handler; passing it here is what checks that what arrived is what the protocol said would arrive.

Example

protocol_machine.accept(at: channel, message: name, actions: [], then: fn(next) {
  greeting(next, name)
})

Drive the position the machine is about to reach, without waiting for the peer.

A machine only acts when an event arrives, but a Send position has nothing to wait for: the protocol says it is this side’s turn to speak. Include this in a transition’s actions and the next position is handed a synthetic event immediately, so it can transmit and move on.

The event arrives as Cast(content), because gen_statem internal events surface that way.

Example

// Take the name, then immediately wake the Send position that follows it.
protocol_machine.accept(
  at: channel,
  message: name,
  actions: [protocol_machine.advance_now(Proceed)],
  then: fn(next) { greeting(next, name) },
)

Take a step from a generated position, along a route that reaches it.

pacta/protocol/emit writes protocols that repeat as flat named positions, because a type that loops cannot be written any other way. A name like that is not a Send or a Recv, so the transitions below will not take it directly: the generated module has a function turning the name into the shape it stands for, and this is what threads a transition through one of those.

Nothing new is asserted here. route is the generated function, and supplying it is what ties the two positions together; a ProtocolTransition carries no protocol inside it, so relabelling one is only ever as sound as the route handed in.

The routes worth knowing about are the ones a generated module writes for a choice of three or more arms. core branches two ways at a time, so a wider choice nests, and a route walks the whole nest in one step. That is what keeps one arm to one case clause here instead of one arm per level.

Example

fn at_session(channel: Channel(teller.Session, Wire)) -> Position(teller.Session) {
  protocol_machine.state(
    tag: Serving,
    at: channel,
    data: Nil,
    handler: fn(event, channel, _data) {
      case event {
        state_machine.Cast(Deposit(amount)) ->
          protocol_machine.along(
            at: channel,
            route: teller.session_deposit,
            step: protocol_machine.accept(
              at: _,
              message: amount,
              actions: [],
              then: fn(next) { at_balance(next) },
            ),
          )

        _ -> protocol_machine.postpone()
      }
    },
  )
}

Take a question and answer it in one step.

Only compiles at patterns.Serve(question, answer, then). Collapsing the receive and the send into one transition buys more than brevity: written longhand the send needs its own position and an advance_now to wake it, because a Send position has nothing to wait for. Here the whole fragment runs while the triggering event is still in hand.

The answer goes to the continuation rather than on the wire, since this module does no I/O.

Example

protocol_machine.answer(
  at: channel,
  question: account,
  with: fn(account) { ledger.balance(account) },
  actions: [],
  then: fn(balance, next) {
    process.send(customer, Balance(balance))
    idle(next)
  },
)

Complete the protocol and stop the machine normally.

Only compiles at Done, so a machine that still owes the peer a message cannot hang up on it. Drops the channel’s monitor.

Example

protocol_machine.complete(at: channel, actions: [state_machine.reply(from, Ok(Nil))])

Take a proposal and decide which way the protocol goes, in one step.

Only compiles at patterns.Decide(proposal, accepted, rejected). Both outcomes need a continuation, so neither can be forgotten, and because they are separate arguments they may lead to genuinely different protocols.

Tell the peer which way you went, or their matching Offer cannot follow.

Example

protocol_machine.decide(
  at: channel,
  proposal: offer,
  choosing: fn(offer) { offer.price <= budget },
  actions: [],
  accepted: fn(next) {
    process.send(seller, Accepted)
    settling(next)
  },
  rejected: fn(next) {
    process.send(seller, Rejected)
    walking_away(next)
  },
)

Abandon the protocol and stop the machine, owing whatever is still owed.

The counterpart to complete, for giving up rather than finishing: a peer that died, a timeout that expired, a precondition that failed. Drops the channel’s monitor. Because it is valid anywhere it proves nothing about the protocol, which is why it is named differently from complete.

Follow the branch the peer selected, with a continuation ready for either.

The difference from follow_left and follow_right is that both continuations are arguments, so a branch cannot be left unhandled: the compiler counts arguments. This is the guarantee ST-DESIGN.md wanted from a List(BranchHandler) and could not get, because a list has no arity the compiler knows about.

Example

let taken = case announcement {
  CarryOn -> protocol_machine.Left
  HangUp -> protocol_machine.Right
}

protocol_machine.follow(
  at: channel,
  taking: taken,
  actions: [],
  left: fn(next) { chatting(next) },
  right: fn(next) { saying_goodbye(next) },
)

Follow the left branch, which the peer selected.

Only compiles at Offer(left, right). Which branch they took is a runtime fact learned by matching on the message that arrived; this turns it back into a static position. The case doing the matching is where Gleam’s ordinary exhaustiveness checking makes sure every branch has a continuation.

Follow the right branch, which the peer selected.

Stay at this position, with new internal data.

For accumulating between protocol steps: counting attempts, appending to a buffer. It moves no protocol, so the next event arrives at the same position with the same handler.

Create a builder from the position the protocol starts at.

Example

protocol_machine.new(awaiting_name(channel))
|> protocol_machine.start_link

Set a hook called whenever a handler returns reject.

Useful for logging or metering protocol violations in one place rather than at every rejection site.

Example

protocol_machine.on_violation(builder, fn(violation) {
  io.println("protocol violation: " <> violation.reason)
})

Take a branch that is this machine’s to choose, with a continuation ready for either.

The counterpart to follow, for Choose rather than Offer. Tell the peer which way you went, or their matching Offer cannot follow.

Example

protocol_machine.pick(
  at: channel,
  taking: case data.attempts > 3 {
    True -> protocol_machine.Right
    False -> protocol_machine.Left
  },
  actions: [],
  left: fn(next) { retrying(next) },
  right: fn(next) { giving_up(next) },
)

Take the left branch of a choice that is this machine’s to make.

Only compiles at Choose(left, right). Tell the peer which branch you took, or their matching Offer cannot follow.

Take the right branch of a choice that is this machine’s to make.

Wait: this event arrived out of protocol order.

Lowers to gen_statem’s postpone, so the event is held and redelivered after the next position change, when a handler that wants it may be in place. This is the right answer for a message that is legitimate but early, and the wrong one for a message that is simply invalid: postponing that leaks, because nothing will ever consume it. Use reject for those.

Example

case event {
  state_machine.Cast(Name(name)) -> protocol_machine.accept(...)
  // Not what this position is waiting for, but may be later.
  _ -> protocol_machine.postpone()
}

Refuse this event as a protocol violation, and stay where you are.

The position is untouched, the on_violation hook fires, and the actions still run so a pending caller can be told why. This is the graceful degradation path: a peer that speaks out of turn should not take the machine down with it.

Example

protocol_machine.reject("capture requires an authorised payment", [
  state_machine.reply(from, Error(NotAuthorised)),
])

Start the machine without linking it to the caller.

Start the machine linked to the caller.

Shorthand for to_state_machine followed by state_machine.start_link.

Bind a handler to a channel at a known position.

This is where a position is erased: channel is captured inside the returned value at its static type, and everything outside sees a value with no protocol in it. That is what lets positions of different types live in one machine.

tag is the gen_statem state for as long as the machine sits here, so keep it small and comparable, and distinct from other positions’ tags.

Example

fn awaiting_name(channel: Channel(Greeter, Wire)) -> Position(Greeter) {
  protocol_machine.state(
    tag: AwaitingName,
    at: channel,
    data: Nil,
    handler: fn(event, channel, data) {
      case event {
        state_machine.Cast(Name(name)) ->
          protocol_machine.accept(at: channel, message: name, actions: [],
            then: fn(next) { greeting(next, name) })
        _ -> protocol_machine.postpone()
      }
    },
  )
}

Lower this builder to a plain state_machine.Builder.

Everything eparch/state_machine offers (naming, hibernation, debug flags, with_state_enter, on_format_status) is applied at that level rather than duplicated here.

Example

protocol_machine.new(awaiting_name(channel))
|> protocol_machine.to_state_machine
|> state_machine.named(state_machine.Local(name))
|> state_machine.start_link

Transmit the message the protocol calls for, then continue.

Only compiles at Send(message, then), and only for the payload type the protocol declared. The checked message is handed to the continuation so it can go on the wire there: this module does no I/O.

Example

protocol_machine.transmit(
  at: channel,
  message: "hello " <> name,
  actions: [],
  then: fn(greeting, next) {
    process.send(peer, Greeting(greeting))
    awaiting_farewell(next)
  },
)

Arm a state timeout every time the machine reaches a new position.

A protocol that stalls halfway through should not sit there forever. The timer is re-armed on each move, so it measures time spent waiting at one position, and it is delivered as an ordinary Timeout event that the current handler can answer however it likes (usually with fail).

Example

protocol_machine.with_timeout(builder, after: 5000, sending: SessionStalled)