246 lines
6.3 KiB
Plaintext
246 lines
6.3 KiB
Plaintext
|
= RFC-0010: Eventbus design and implementation
|
||
|
:toc: preamble
|
||
|
:toclevels: 3
|
||
|
ifdef::env-github[]
|
||
|
:tip-caption: :bulb:
|
||
|
:note-caption: :information_source:
|
||
|
:important-caption: :heavy_exclamation_mark:
|
||
|
:caution-caption: :fire:
|
||
|
:warning-caption: :warning:
|
||
|
endif::[]
|
||
|
|
||
|
.**RFC Template**
|
||
|
|
||
|
.Metadata
|
||
|
[cols="1h,1"]
|
||
|
|===
|
||
|
| RFC
|
||
|
| 0010
|
||
|
|
||
|
| Title
|
||
|
| Eventbus design and implementation
|
||
|
|
||
|
| Sponsor
|
||
|
| https://github.com/rtyluer[R Tyler Croy]
|
||
|
|
||
|
| Status
|
||
|
| Not Submitted :information_source:
|
||
|
|
||
|
| Type
|
||
|
| Standard
|
||
|
|
||
|
| Created
|
||
|
| 2020-06-20
|
||
|
|
||
|
|===
|
||
|
|
||
|
== Abstract
|
||
|
|
||
|
THe eventbus is the core of the Otto ecosystem, which provides stateless
|
||
|
link:https://en.wikipedia.org/wiki/Publish-subscribe_pattern[pubsub]
|
||
|
channels and stateful queues over
|
||
|
link:https://en.wikipedia.org/wiki/WebSocket[WebSocket]
|
||
|
connections.
|
||
|
|
||
|
Other services in the Otto ecosystem are expected to register for events by
|
||
|
subscribing to different channels. Events from these channels will be received
|
||
|
over a single WebSocket connection.
|
||
|
|
||
|
== Specification
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Provide a detailed specification what is being proposed. Be as technical and
|
||
|
detailed as needed to allow new or existing developers to reasonably understand
|
||
|
the scope/impact of an implementation.
|
||
|
|
||
|
* Use present tense - describe what the proposal "does" (as if it were already done) not what it will do.
|
||
|
* Do not discuss alternative designs that were rejected, those belong in the Reasoning section.
|
||
|
* Avoid in-depth discussion or justification of design choices, that belongs in the Reasoning section.
|
||
|
====
|
||
|
|
||
|
|
||
|
=== Events
|
||
|
|
||
|
==== Register
|
||
|
|
||
|
The register message is required in order to identify the client with the eventbus for
|
||
|
all future communications. The `register` event will also ensure that an "inbox" is
|
||
|
created for the sending client, allowing it to receive unicasted messages.
|
||
|
|
||
|
[source,json]
|
||
|
----
|
||
|
{
|
||
|
"type" : "register",
|
||
|
"value" : {
|
||
|
"uuid" : "some-uuid-string", // <1>
|
||
|
"token" : "optional-auth-token" // <2>
|
||
|
}
|
||
|
}
|
||
|
----
|
||
|
<1> The UUID should be the client's own identifier which is guaranteed to be identical between restarts
|
||
|
<2> The `token` is optional for first-time clients, but required for reconnecting clients to resume their previous identifier
|
||
|
|
||
|
===== Responses
|
||
|
|
||
|
.Success
|
||
|
[source,json]
|
||
|
----
|
||
|
{
|
||
|
"type" : "registered",
|
||
|
"value" : {
|
||
|
"token" : "client's auth token" // <1>
|
||
|
}
|
||
|
}
|
||
|
----
|
||
|
<1> The client's secret authentication token to use in the future
|
||
|
|
||
|
Errors:
|
||
|
|
||
|
* Invalid auth token for identifier
|
||
|
* Client already registered
|
||
|
|
||
|
|
||
|
|
||
|
==== Subscribe
|
||
|
|
||
|
[source,json]
|
||
|
----
|
||
|
{
|
||
|
"type" : "subscribe",
|
||
|
"value" : {
|
||
|
"client" : {
|
||
|
"uuid" : "client-uuid",
|
||
|
"token" : "auth-token"
|
||
|
},
|
||
|
"channel" : "/channel/identifier"
|
||
|
}
|
||
|
}
|
||
|
----
|
||
|
|
||
|
===== Responses
|
||
|
|
||
|
.Success
|
||
|
[source,json]
|
||
|
----
|
||
|
{
|
||
|
"type" : "subscribed",
|
||
|
"value" : {
|
||
|
"client" : "client-uuid",
|
||
|
"channel": "/channel/identifier"
|
||
|
}
|
||
|
}
|
||
|
----
|
||
|
|
||
|
|
||
|
.Error
|
||
|
[source,json]
|
||
|
----
|
||
|
{
|
||
|
"type" : "error",
|
||
|
"value" : {
|
||
|
"code" : 10, // <1>
|
||
|
"msg" : "errors.subscription_failed" // <2>
|
||
|
}
|
||
|
}
|
||
|
----
|
||
|
<1> A predefined error code matching the message
|
||
|
<2> A string denoting which type of error message should be shown to the user
|
||
|
|
||
|
|
||
|
== Motivation
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Explain why the existing code base or process is inadequate to address the problem that the RFC solves.
|
||
|
This section may also contain any historal context such as how things were done before this proposal.
|
||
|
|
||
|
* Do not discuss design choices or alternative designs that were rejected, those belong in the Reasoning section.
|
||
|
====
|
||
|
|
||
|
== Reasoning
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Explain why particular design decisions were made.
|
||
|
Describe alternate designs that were considered and related work, e.g. how the feature is supported in other systems.
|
||
|
Provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
|
||
|
|
||
|
* Use sub-headings to organize this section for ease of readability.
|
||
|
* Do not talk about history or why this needs to be done, that is part of Motivation section.
|
||
|
====
|
||
|
|
||
|
== Backwards Compatibility
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Describe any incompatibilities and their severity.
|
||
|
Describe how the RFC proposes to deal with these incompatibilities.
|
||
|
|
||
|
If there are no backwards compatibility concerns, this section may simply say:
|
||
|
There are no backwards compatibility concerns related to this proposal.
|
||
|
====
|
||
|
|
||
|
== Security
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Describe the security impact of this proposal.
|
||
|
Outline what was done to identify and evaluate security issues,
|
||
|
discuss of potential security issues and how they are mitigated or prevented,
|
||
|
and how the RFC interacts with existing permissions, authentication, authorization, etc.
|
||
|
|
||
|
If this proposal will have no impact on security, this section may simply say:
|
||
|
There are no security risks related to this proposal.
|
||
|
====
|
||
|
|
||
|
|
||
|
== Testing
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
If the RFC involves any kind of behavioral change to code give a summary of how
|
||
|
its correctness (and, if applicable, compatibility, security, etc.) can be
|
||
|
tested.
|
||
|
|
||
|
In the preferred case that automated tests can be developed to cover all
|
||
|
significant changes, simply give a short summary of the nature of these tests.
|
||
|
|
||
|
If some or all of changes will require human interaction to verify, explain why
|
||
|
automated tests are considered impractical. Then summarize what kinds of test
|
||
|
cases might be required: user scenarios with action steps and expected
|
||
|
outcomes. Might behavior vary by platform (operating system, servlet
|
||
|
container, web browser, etc.)? Are there foreseeable interactions between
|
||
|
different permissible versions of components?
|
||
|
Are any special tools, proprietary software, or online service accounts
|
||
|
required to exercise a related code path (Active Directory server, GitHub
|
||
|
login, etc.)? When will testing take place relative to merging code changes,
|
||
|
and might retesting be required if other changes are made to this area in the
|
||
|
future?
|
||
|
|
||
|
If this proposal requires no testing, this section may simply say:
|
||
|
There are no testing issues related to this proposal.
|
||
|
====
|
||
|
|
||
|
== Prototype Implementation
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Link to any open source reference implementation of code changes for this proposal.
|
||
|
The implementation need not be completed before the RFC is accepted
|
||
|
but must be completed before the RFC is given "final" status.
|
||
|
|
||
|
RFCs which will not include code changes may omit this section.
|
||
|
====
|
||
|
|
||
|
== References
|
||
|
|
||
|
[TIP]
|
||
|
====
|
||
|
Provide links to any related documents. This will include links to discussions
|
||
|
on the mailing list, pull requests, and meeting notes.
|
||
|
====
|
||
|
|
||
|
|
||
|
|