Invite-related events

[crwood]

As a follow-up for #686 (comment) and after #694, consider also emitting "events" messages for the recently-added operations relating to magic-folder invites. Examples of such messages might be something like:

{"event": "invite-created", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge" }
{"event": "invite-updated", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge", "state": "Offer sent; waiting for response" }
{"event": "invite-succeeded", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge" }
{"event": "invite-failed", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge", "reason": "Key-confirmation failed" }
{"event": "invite-rejected", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge" }
{"event": "invite-cancelled", "folder": "Cat Pics", "participant-name": "Bob's Laptop", "id": "40fe4a79-5012-40dc-9574-ae2160b57797", "wormhole-code": "7-guitarist-revenge" }

"Events" messages like these would prevent clients from having to manually query the .../invites endpoint in order to track state-related information and/or remove the need to await on (and, e.g., keep a reference to the Deferred for) the result of the .../invite-wait endpoint. In addition, having an "invite-updated" event for each "phase" of the invite process would allow for finer-grained progress messages to be displayed to the user (since, currently, .../invite-wait will only show the "final result" of an invite; there is no way to get intermediate/progress information without polling).

[exarkun]

Should the wormhole code itself appear in these events?

[meejah]

Should the wormhole code itself appear in these events?

I would lean towards "no" at first -- but also, the API reveals and accepts secret information so there's no particular reason not to in that sense. (However, the wormhole-code should be in the JSON returned from the creation endpoint, which I assume is sufficient for most UIs?)

[meejah]

Do we want something more rigorous for the "state"? (the example looks like a free-form string, which probably has i18n problems at least .. I'm thinking something easy like "a list of permitted strings").

Walking through the code, we could at most include something for each await / yield basically. So that's:

• "start": nothing happened yet
• "welcome": we've gotten the welcome from the server (bonus: this gives us a good place to hang the "MotD" which in Winden's case includes a terms-of-service message)
• "code": we've allocated a nameplate + code
• "versions": we've gotten the "versions" message
• "offer": we've sent the invite (we don't strictly "await" here, so we only know we wrote bytes not that the server got them...)
• "reply": we've received the reply
• "added": we've added the participant (to the Tahoe Mutable)
• "done": we've sent the final reply message (again, just know we've written bytes).
• "closed": the wormhole has been closed (from our side).

That's the happy-path. For "proper" progress we might want to include a notion of "step N of K" as well (i.e. so you can show a progress-bar or similar). Or this could be represented as "percent-done" I guess.

[meejah]

(Getting "versions" means you've communicated with the other side)

[crwood]

(However, the wormhole-code should be in the JSON returned from the creation endpoint, which I assume is sufficient for most UIs?)

Including the code would allow clients who did not initiate the invite to discover it immediately. I could see this being useful if, e.g., we want a GUI that displays and presents the state of all invites -- including those initiated by the magic-folder CLI... Is that something we would want to support? (There's nothing to stop such a GUI from fetching the code manually via a GET request to .../invites; this is mostly a question of expected behavior for future functionality).

Do we want something more rigorous for the "state"? (the example looks like a free-form string, which probably has i18n problems at least .. I'm thinking something easy like "a list of permitted strings").

Yes, agreed. That was intended just an example. Having some list of pre-defined strings that clients could reference (like the ones you've outlined) would be much better. :)

[meejah]

One semantic reason to keep it out of "mere status updates" is that it's a one-time use code, so even if a different UI initiated something it seems like no other interface should show the code to a human -- but also it's relatively easy to add later (especially if we're taking the "be tolerant of new stuff" approach to versioning instead of incrementing the version a lot).

But as pointed out above, any other UI can still get at it...