sans-io.md (d8bfae6) - fakesshagent.git

sans-io.md

# `fakesshagent` wish sans-io

???+ wish "Wish details: `fakesshagent` should be a Sans-I/O implementation of the SSH agent protocol"
    <table id="bug-summary" markdown>
        <tr><th scope=col>Class<td><i>wish</i><td>This is a request for an enhancement.
        <tr><th scope=col>Priority<td><i>high</i><td>This should be fixed in the next release.
        <tr><th scope=col>Difficulty<td><i>fun</i><td>Just needs tuits, and not many of them.
        <tr><th scope=col>Requested-in<td colspan=2>0.1
    </table>

The fake/stub SSH agent in version 0.1 of `fakesshagent` is almost a [Sans-I/O][SANS_IO] protocol parser.[^sans-io]
However, it currently neither has separate business logic---the "stub" part is intertwined with the "parser" part---nor does it implement a Sans-I/O-style "stream of events" interface (because the business logic is not yet separate).
It should have/do both.

Actually separating the business logic from the parser, Sans-I/O-style, would also enable porting the remaining SSH test double of [`derivepassphrase`][DERIVEPASSPHRASE]: the `AgentRequestResponseQueue`, which maps protocol requests to a list of protocol responses.[^difference-queue-and-stub-agent]
The queue thus already operates on (a primitive version of) the event-based interface.

* * *

<b>Therefore</b>, rewrite the fake/stub agent into a parser and a (proper) stub agent, and have the parser expose a Sans-I/O-style "stream of events" interface.

[^sans-io]:
  In a Sans-I/O network protocol parser, the parser and the network I/O machinery are completely separate, enabling the parser to be used under all kinds of different I/O paradigms.
  Porting I/O paradigms is usually practically infeasible, and if the protocol parser were intertwined with the I/O, then the parser would likely need to be rewritten from scratch.

[^difference-queue-and-stub-agent]:
  The `AgentRequestResponseQueue` differs from the fake/stub agent in that the queue only understands the protocol framing, not the protocol contents.
  The queue requires and enforces well-formed requests and responses, and will always answer the same request in the same way, irrespective of session state.
  It is thus less flexible, but also easier to set up.

[DERIVEPASSPHRASE]: https://the13thletter.info/derivepassphrase/
[SANS_IO]: https://sans-io.readthedocs.io/

fakesshagent.git

Add wish sans-io