Skip to content

Commit

Permalink
Documentation of kafka-ws intercommunication (#85)
Browse files Browse the repository at this point in the history 
Obtaining a ticket and connecting via websocket
  • Loading branch information
@thiagodpf
thiagodpf committed Aug 31, 2020
1 parent 685b9fc commit cd88415
Show file tree
Hide file tree
Showing 2 changed files with 186 additions and 11 deletions.
80 changes: 80 additions & 0 deletions source/internal-communication.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -552,12 +552,92 @@ will sign a certificate and link this certificate to the device registration.
The ``x509-identity-mgmt`` component is responsible for providing
certificate-related services for devices.
Kafka-WS
---------------------
*Kafka WebSocket* service allows the users to retrieve conditional and/or
partial real time data from a given dojot topic in its internal Kafka cluster.
Behavior when requesting a ticket and a websocket connection
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Below we can understand the behavior of the Kafka-WS service when a user
(through a `user agent`_) requests a ticket in order to establish a
communication via websocket with Kafka-WS.
Note that when the user requests a new ticket, Kafka-WS extracts some
information from the *user's access token* (`JWT`_) and generates a
*signed payload*, to be used later in the decision to authorize (or not)
the websocket connection. From the payload a *ticket* is generated and
both are stored in Redis, where the ticket is the key to obtain the payload.
A `TTL`_ is defined by Kafka-WS, so the user has to use the ticket within the
established time, otherwise, Redis automatically deletes the ticket and payload.
After obtaining the ticket, the user makes an HTTP request to Kafka-WS
requesting an upgrade to communicate via *websocket*. As the specification of
this HTTP request limits the use of additional headers, it is necessary to send
the ticket through the URL, so that it can be validated by Kafka-WS before
authorizing the upgrade.
Since the ticket is valid, that is, it corresponds to an entry on Redis,
Kafka-WS retrieves the payload related to the ticket, verifies the integrity
of the payload and deletes that entry on Redis so that the ticket cannot be
used again.
With the payload it is possible to make the decision to authorize the upgrade
to websocket or not. If authorization is granted, Kafka-WS opens a subscription
channel based on a specific topic in Kafka. From there, the upgrade to websocket
is established and the user starts to receive data as they are being published
in Kafka.
.. uml::
:caption: Obtaining a ticket and connecting via websocket
:align: center
actor User
boundary Kong
control "Kafka-WS"
database Redis
control Kafka
group Get Ticket
User -> Kong: GET /kafka-ws/v1/ticket\nHeaders="Authorization: JWT"
Kong -> Kong: Checks JWT
Kong -> "Kafka-WS" : Request a ticket
"Kafka-WS" -> "Kafka-WS" : Sign the payload and\ngenerate a ticket for it
"Kafka-WS" -> Redis : Register the ticket and\npayload with a TTL
"Kafka-WS"<-- Redis : Sucess
User <-- "Kafka-WS" : Returns the newly generated ticket
end
group Connect via websocket
User -> Kong: Upgrade HTTP to websocket\n(ticket in the URL)
Kong -> "Kafka-WS" : Forward the ticket
"Kafka-WS" -> Redis : Recovers payload (if any)
"Kafka-WS"<-- Redis : Payload found
"Kafka-WS" -> "Kafka-WS" : Checks the payload
"Kafka-WS" -> Kafka : Subscrive to kafka topic\n(Using the payload)
"Kafka-WS" <-- Kafka : Sucess
User <-- "Kafka-WS" : Upgrade to websocket accepted\nConnected!
"Kafka-WS" <-- Kafka : New data in the topic
User <-- "Kafka-WS" : Returns data
"Kafka-WS" <-- Kafka : [...]
User <-- "Kafka-WS" : [...]
"Kafka-WS" <-- Kafka : [...]
User <-- "Kafka-WS" : [...]
end
.. _API - data-broker: https://dojot.github.io/data-broker/apiary_latest.html
.. _Kafka partitions and replicas: https://sookocheff.com/post/kafka/kafka-in-a-nutshell/#what-is-kafka
.. _DataBroker documentation: https://dojot.github.io/data-broker/apiary_latest.html
.. _Device Manager messages: https://dojotdocs.readthedocs.io/projects/DeviceManager/en/latest/kafka-messages.html
.. _CA: https://en.wikipedia.org/wiki/Certificate_authority
.. _CSR: https://en.wikipedia.org/wiki/Certificate_signing_request
.. _user agent: https://en.wikipedia.org/wiki/User_agent
.. _TTL: https://en.wikipedia.org/wiki/Time_to_live
.. _JWT: https://en.wikipedia.org/wiki/JSON_Web_Token
.. _Kafka's official documentation: https://kafka.apache.org/documentation/
.. _Kong's documentation: https://docs.konghq.com/0.14.x/getting-started/configuring-a-service/
.. _Kong JWT plugin page: https://docs.konghq.com/hub/kong-inc/jwt/
Expand Down
117 changes: 106 additions & 11 deletions source/locale/pt_BR/LC_MESSAGES/internal-communication.po
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ msgid ""
msgstr ""
"Project-Id-Version: dojot 0.4.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2020-08-27 14:48-0300\n"
"POT-Creation-Date: 2020-08-28 14:31-0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
Expand Down Expand Up @@ -633,16 +633,108 @@ msgid ""
"device registration. The ``x509-identity-mgmt`` component is responsible "
"for providing certificate-related services for devices."
msgstr ""
"A plataforma dojot possui internamente uma autoridade certificadora (`CA`_) "
"capaz de emitir certificados x.509 para que os dispositivos possam se "
"comunicar com a plataforma através de um canal seguro (usando o protocolo "
"TLS). Ao requisitar um certificado para a plataforma, é necessário informar "
"um `CSR`_, o qual passará por uma série de validações até chegar na "
"Autoridade Certificadora interna, que por sua vez, se todas as verificações "
"passarem com sucesso, assinará um certificado e vinculará este certificado "
"ao registro do dispositivo. O componente ``x509-identity-mgmt`` é responsável "
"por oferecer os serviços relacionados a certificados para dispositivos."

"A plataforma dojot possui internamente uma autoridade certificadora "
"(`CA`_) capaz de emitir certificados x.509 para que os dispositivos "
"possam se comunicar com a plataforma através de um canal seguro (usando o"
" protocolo TLS). Ao requisitar um certificado para a plataforma, é "
"necessário informar um `CSR`_, o qual passará por uma série de validações"
" até chegar na Autoridade Certificadora interna, que por sua vez, se "
"todas as verificações passarem com sucesso, assinará um certificado e "
"vinculará este certificado ao registro do dispositivo. O componente "
"``x509-identity-mgmt`` é responsável por oferecer os serviços "
"relacionados a certificados para dispositivos."

#: ../../source/internal-communication.rst:556
msgid "Kafka-WS"
msgstr ""

#: ../../source/internal-communication.rst:558
msgid ""
"*Kafka WebSocket* service allows the users to retrieve conditional and/or"
" partial real time data from a given dojot topic in its internal Kafka "
"cluster."
msgstr ""
"O serviço *Kafka WebSocket* permite aos usuários a recuperação parcial e/ou "
"condicional de dados em tempo real de um determinado tópico do cluster Kafka "
"interno da dojot."

#: ../../source/internal-communication.rst:562
msgid "Behavior when requesting a ticket and a websocket connection"
msgstr "Comportamento ao solicitar um ticket e uma conexão websocket"

#: ../../source/internal-communication.rst:564
msgid ""
"Below we can understand the behavior of the Kafka-WS service when a user "
"(through a `user agent`_) requests a ticket in order to establish a "
"communication via websocket with Kafka-WS."
msgstr ""
"Abaixo podemos entender o comportamento do serviço Kafka-WS quando um "
"usuário (por meio de um `user agent`_) solicita um ticket para "
"estabelecer uma comunicação via websocket com Kafka-WS."

#: ../../source/internal-communication.rst:568
msgid ""
"Note that when the user requests a new ticket, Kafka-WS extracts some "
"information from the *user's access token* (`JWT`_) and generates a "
"*signed payload*, to be used later in the decision to authorize (or not) "
"the websocket connection. From the payload a *ticket* is generated and "
"both are stored in Redis, where the ticket is the key to obtain the "
"payload. A `TTL`_ is defined by Kafka-WS, so the user has to use the "
"ticket within the established time, otherwise, Redis automatically "
"deletes the ticket and payload."
msgstr ""
"Observe que quando o usuário solicita um novo ticket, o Kafka-WS extrai "
"algumas informações do *token de acesso do usuário* (`JWT`_) e gera um "
"*payload assinado*, para ser usado posteriormente na decisão de autorizar"
" (ou não) a conexão via websocket. A partir do payload, é gerado um "
"*ticket* e os dois são armazenados no Redis, onde o ticket é a chave para"
" obter o payload. Um `TTL`_ é definido pelo Kafka-WS, então o usuário "
"deve usar o ticket dentro do tempo estabelecido, caso contrário, o Redis "
"apaga automaticamente o ticket e o payload."

#: ../../source/internal-communication.rst:576
msgid ""
"After obtaining the ticket, the user makes an HTTP request to Kafka-WS "
"requesting an upgrade to communicate via *websocket*. As the "
"specification of this HTTP request limits the use of additional headers, "
"it is necessary to send the ticket through the URL, so that it can be "
"validated by Kafka-WS before authorizing the upgrade."
msgstr ""
"Após obter o ticket, o usuário faz uma solicitação HTTP ao Kafka-WS "
"requisitando um upgrade de protocolo para se comunicar via *websocket*. "
"Como a especificação dessa solicitação HTTP limita o uso de cabeçalhos "
"adicionais, é necessário enviar o ticket pela URL, para que possa ser "
"validado pelo Kafka-WS antes de autorizar o upgrade."

#: ../../source/internal-communication.rst:582
msgid ""
"Since the ticket is valid, that is, it corresponds to an entry on Redis, "
"Kafka-WS retrieves the payload related to the ticket, verifies the "
"integrity of the payload and deletes that entry on Redis so that the "
"ticket cannot be used again."
msgstr ""
"Dado que o ticket esteja válido ou seja, corresponde a uma entrada no "
"Redis, o Kafka-WS recupera o payload relacionado ao ticket, verifica sua "
"integridade e exclui essa entrada no Redis para que o ticket "
"não possa ser usado novamente."

#: ../../source/internal-communication.rst:587
msgid ""
"With the payload it is possible to make the decision to authorize the "
"upgrade to websocket or not. If authorization is granted, Kafka-WS opens "
"a subscription channel based on a specific topic in Kafka. From there, "
"the upgrade to websocket is established and the user starts to receive "
"data as they are being published in Kafka."
msgstr ""
"Com o payload é possível tomar a decisão de autorizar ou não o upgrade "
"para websocket. Se a autorização for concedida, o Kafka-WS abre um canal "
"de subscrição com base em um tópico específico no Kafka. A partir daí, o "
"upgrade para websocket é estabelecido e o usuário começa a receber os "
"dados à medida que vão sendo publicados no Kafka."

#: ../../source/internal-communication.rst:593
msgid "Obtaining a ticket and connecting via websocket"
msgstr "Obtenção de ticket e conexão via websocket"

#~ msgid "dojot components"
#~ msgstr "componentes dojot"
Expand All @@ -656,3 +748,6 @@ msgstr ""
#~ msgid "Current dojot components are shown in :numref:`dojot_components`."
#~ msgstr ""

#~ msgid "Kafka-ws"
#~ msgstr ""

0 comments on commit cd88415

Please sign in to comment.