Como eu documentei um protocolo de comunicação sobre filas e canais de mensagens?

5

Estou trabalhando em um grande projeto no momento e estou tentando documentar o protocolo de comunicação que fica no topo de um middleware de fila de mensagens.

A documentação destina-se a outra organização que irá implementar um novo back-end para o cliente.

O formato das mensagens usa buffers de protocolo, então estou menos interessado em descrever o formato de ligação.

Estou interessado em documentar as interações entre o serviço e o cliente. Uma interação típica pode ser algo como:

  1. Cliente inscreve-se no Canal1
  2. O cliente envia RequestForStream para o Queue1
  3. As leituras de serviço do Queue1 publicam StreamResponse (contendo o ponto de extremidade para o qual se inscrever, Canal2) para o Canal1 e, se tiverem êxito, começarão a publicar as notificações no Canal2
  4. O cliente recebe do Canal1 e assina o Canal2
  5. Mais coisas ...

Como posso documentar melhor os cenários como este? Alguém sabe de algum exemplo de interações documentadas com filas e canais?

Editar: não estou escrevendo uma fila de mensagens. Estou usando um middleware semelhante ao JMS chamado Nirvana . Quero documentar o aplicativo criado no topo do sistema Message Queue.

Editar 2: Na UML, como eu modelaria uma fila ou um canal? Eu mostraria eles em um diagrama de seqüência?

    
por Dave Hillier 28.02.2013 / 11:04
fonte

2 respostas

2

Eu sou o autor do pg_message_queue, que é um sistema de canal / fila muito leve no PostgreSQL projetado para facilitar a integração em nível de banco de dados. As mensagens podem então ser encaminhadas para uma fila de mensagens mais pesada, ou algo semelhante, ou podem ser processadas. O caso de uso é para coisas como "Eu quero enviar um e-mail do banco de dados" e ajuda a resolver o problema do PostgreSQL sem problemas de processamento transacional que podem resultar.

Nossa documentação está no link

Eu não direi que é a melhor documentação disponível, mas é suficiente para nosso caso de uso. Compare ao link que é a documentação do rabbitmq e você verá como os requisitos da documentação são diferentes.

Mas, como todos os documentos, mantenha seu público-alvo e use o caso em mente e passe por isso conceitualmente e de forma programática.

Editar Ok, vejo o que entendi errado. Eu sugiro começar pelo menos com um esboço de documentação técnica. Se você tem de outra pessoa, ótimo. Se não, pelo menos, elabore um resumo do que um manual de programador técnico deve cobrir.

Parece-me que você está procurando documentar um protocolo de rede em vez de uma API. Desculpe, eu li e perdi essa parte. Ainda não está claro para mim se isso é direto sobre TCP, ou sobre HTTP, ou outra coisa. Na medida em que você está reutilizando outros protocolos, o trabalho é mais fácil.

De qualquer forma, eu dividiria a documentação em três seções. O primeiro cobriria a estrutura da mensagem em geral. Isso incluiria cabeçalhos, especificações do corpo da mensagem etc., mas estaria em um nível geral suficiente para fornecer uma referência para a seção 2.

A seção 2 cobriria as especificidades de cada tipo de mensagem. Mais uma vez, depende do que exatamente você está reutilizando a profundidade que você precisa para entrar.

A Seção 3 forneceria exemplos de como a comunicação funcionaria usando conjuntos de mensagens simuladas.

    
por 28.02.2013 / 11:48
fonte
2

Eu usei o pi-calculus para documentar e analisar processos de alto nível. Não existe uma linguagem padrão para pi-calculus, mas para uma ferramenta que escrevi usei uma simples linha de uma linha por etapa atômica, que seria algo como:

process Client
    # initialise client process with the channel to subscribe to 
    recv self Init ( channel1 : channel, queue1 : channel ) 
    # send request to server
    send queue1 RequestForStream ( channel1 )
    # bind channel in response to channel2
    recv channel1 StreamResponse ( channel2 : channel )

    loop:
    choice
        # either receive a notification or stop
        recv channel2 Notification ()
            goto loop
        recv channel2 Stop()
            stop

process Server
    new channel2
    # wait for request
    recv self RequestForStream ( client : channel )
    # send response to client with channel2 to send
    send client StreamResponse ( channel2 ) 
    # send notifications on channel2
    send channel2 Notification ()
    send channel2 Notification ()
    send channel2 Stop ()
    stop


# test
process Test
    c := start Client
    s := start Server

    send c Init ( c, s )
    stop


start Test

as peças de parada extra estão lá como a ferramenta é para detectar deadlocks livelocks e raças.

    
por 28.02.2013 / 14:51
fonte