README.md

Trabalho final - Desenvolvimento de Sistemas Paralelos e Distribuídos

Integrantes

• Guilherme Luiz Lange
• Lucas Moraes Schwambach
• Mateus Lucas Cruz Brandt

Descrição geral do sistema

O sistema é um serviço para troca de mensagens (chat).

Para utilizar, os usuários precisam criar uma conta. A conta é identificada por usuário e senha, e também é possível informar o nome completo.

Para conversar com outro usuário, é necessário ser amigo dele. Para tanto, um pedido de amizade deve ser enviado e aceito. O outro usuário pode rejeitar o pedido. Até aceitar ou rejeitar, o pedido fica pendente.

O conteúdo das mensagens pode ser texto ou um áudio. O servidor na verdade está preparado para mensagens com qualquer conteúdo binário (áudio, imagem etc.) desde que não muito grande (há mensagens put-file e get-file para, respectivamente, armazenar ou recuperar qualquer arquivo binário). A limitação é no cliente Android que suporta somente áudios no momento.

Requisitos funcionais

• RF1: O sistema deverá manter usuários.
• RF2: O sistema deverá manter mensagens.
• RF3: O sistema deverá manter pedidos de amizade.
• RF4: O sistema deverá manter amizades.
• RF5: O sistema deverá permitir comunicação entre usuários através de mensagens.
• RF6: O sistemá deverá permitir o envio de mensagens de áudio.

Regras de negócio

• RN1: Um usuário só pode se comunicar com outro quando for amigo deste.
• RN2: Um usuário só se torna amigo de outro quando o primeiro enviar um pedido de amizade e o segundo aceitar esse pedido.

Especificação das mensagens

Toda mensagem é composta por uma sequência de headers, uma linha em branco, e o corpo da mensagem (JSON ou dados binários). Cada header é um par chave-valor separado por um espaço. Os headers que consideramos são os seguintes:

• operation: Identificador da operação sendo realizada; obrigatório.
• token: Token de acesso. Obrigatório dependendo da request, nem todas precisam.
• body-size: Tamanho do corpo em bytes; obrigatório (mesmo que seja 0).
• file-extension: Extensão do arquivo (.wav, .png); obrigatório nas requests put-file e get-file.

O sistema permite headers que não sejam esses, mas não faz nada com eles.

Esse é o formato das requests. As respostas segue o mesmo formato, mas os headers são diferentes:

• status: Os valores possíveis são ok ou err:<tipo do erro>, onde <tipo do erro> pode ser internal (erro do servidor) ou badRequest (erro do usuário, na request).
• body-size: Tamanho do corpo em bytes (sempre presente, mesmo que seja 0).

Apresentamos a seguir a especificação de cada mensagem. A não ser onde outro formato é especificado, presuma que o formato de todos os corpos de request e response são JSON.

Outro detalhe é que qualquer request com corpo JSON pode ter possível retorno o código de erro FAILED_TO_PARSE_JSON, então omitimos na coluna de "possíves erros".

Tipos de dados

Nome	FriendshipStatus
Possíveis valores	"NO_FRIEND_REQUEST": Usuário não é amigo e não existe nenhum pedido de amizade dele ou enviado para ele "SENT_FRIEND_REQUEST": Usuário não é amigo mas lhe enviou um pedido de amizade "RECEIVED_FRIEND_REQUEST": Usuário não é amigo mas você enviou um pedido de amizade a ele "IS_FRIEND": Usuário é amigo

"Meta"-requests

Essas requisições não tem erros possíveis nem requerem corpos.

Operação	Requer token?	Resposta
get-index	Não	Array com os nomes de todas as operações disponíveis. Por exemplo: ["get-index", "get-all-error-codes", "create-user", "edit-user", ...]

Quando uma operação falha e é necessário informar na resposta o que aconteceu, retornamos um código de erro para que o cliente se responsabilize por mostrar como for melhor. De fato, o cliente Android pode mostrar a mensagem em inglês ou português. A seguinte request é um índice desses códigos de erro.

Qualquer operação, quando falhar, retorna um corpo semelhante a {"messageCode": "INCORRECT_CREDENTIALS"}. Os erros retornados assim são informados na coluna "possíveis erros" das especificações das mensagens.

Operação	Requer token?	Resposta
get-all-error-codes	Não	Array com os nomes de todos os error codes retornados. Por exemplo: ["INTERNAL", "FAILED_TO_PARSE_JSON", "INCORRECT_CREDENTIALS", "FAILED_TO_SEND_FRIEND_REQUEST", ...]

Requests para manter usuários

Operação	create-user
Descrição	Cria uma conta para um usuário novo
Requer token?	Não
Request	username Nome do usuário (único) password Senha fullname Nome completo
Resposta ok	id ID do usuário criado
Possíveis erros	USERNAME_IN_USE FAILED_TO_CREATE_USER

Operação	create-session
Descrição	Operação para fazer login do usuário. Cria uma sessão com um token associado, que é retornado para autenticar o usuário em operações posteriores.
Requer token?	Não
Request	username password
Resposta ok	token Token para ser utilizado no header token para acessos posteriores id ID do usuário fullname Nome completo do usuário Os dois últimos campos retornam os dados do usuário que o cliente não tem (tem somente username e password usados no login) para que tenha os dados completos do usuário.
Possíveis erros	INCORRECT_CREDENTIALS

Operação	edit-user
Descrição	Altera dadaos do usuário
Requer token?	Sim
Request	newFullname Novo nome completo newPassword Nova senha
Resposta ok	Sem resposta
Possíveis erros	INTERNAL Quando não existe usuário com o ID de usuário associado ao token enviado na request. Indica um bug, não deveria ser possível.

Operação	whoami
Descrição	Retorna os dados completos do usuário logado (exceto senha)
Requer token?	Sim
Request	Sem corpo
Resposta ok	username fullname createdAt Timestamp da data de criação do usuário updatedAt Timestamp da data da última alteração dos dados do usuário (`null` caso nunca)
Possíveis erros	Nenhum

Operação	search-users
Descrição	Busca de usuários. Permite filtrar por nome. Tem paginação.
Requer token?	Sim
Request	query Filtro por nome de usuário page Os resultados vem paginados (20 por página), então é necessário informar qual página de resultados está sendo visualizada
Resposta ok	A resposta é um array com os dados dos usuários cujos nomes contém a string dada em query. Os dados de cada usuários retornados são os seguintes: id username fullname friendshipStatus
Possíveis erros	INVALID_PAGE_NUMBER Caso page seja menor que 0.

Operação	end-session
Descrição	Finaliza sessão atual do usuário.
Requer token?	Sim
Request	Sem corpo
Resposta ok	Sem resposta
Possíveis erros	INTERNAL Caso o token enviado não tenha uma sessão correspondente.

Requests para manter amizades

Operação	get-friend-requests
Descrição	Lista pedidos de amizade envolvendo o usuário (enviados por ele ou para ele).
Requer token?	Sim
Request	Sem corpo
Resposta ok	Array de pedidos de amizade, onde cada pedido de amizade é um objeto com os seguintes atributos: from Objeto representando usuário que enviou o pedido: id username fullname to Objeto representando o usuário que recebeu o pedido: id username fullname createdAt Data em que o pedido de amizade foi enviado
Possíveis erros	Nenhum

Operação	send-friend-request
Descrição	Envia pedido de amizade a um outro usuário
Requer token?	Sim
Request	userId ID do usuário a quem o pedido vai ser enviado
Resposta ok	messageCode igual a SENT_FRIEND_REQUEST_SUCCESSFULLY
Possíveis erros	FRIEND_REQUEST_TO_YOURSELF NO_USER_WITH_GIVEN_ID YOU_ALREADY_SENT_FRIEND_REQUEST THEY_ALREADY_SENT_FRIEND_REQUEST ALREADY_FRIENDS FAILED_TO_SEND_FRIEND_REQUEST

Operação	finish-friend-request
Descrição	Finaliza (aceita ou rejeita) um pedido de amizade. Ao aceitar, o usuário se torna amigo. Em ambos os casos, o pedido é simplesmente exluído no final.
Requer token?	Sim
Request	senderId ID do usuário que enviou o pedido. Isso serve para identificar o pedido (há no máximo 1 pedido de amizade por par de usuários) accepted Se o pedido foi aceito ou rejeitado.
Resposta ok	messageCode com mensagem de código FINISHED_FRIEND_REQUEST_SUCCESSFULLY
Possíveis erros	FRIEND_REQUEST_TO_YOURSELF FRIEND_REQUEST_NOT_FOUND Caso o usuário com id senderId não enviou um pedido de amizade a você. FAILED_TO_FINISH_FRIEND_REQUEST

Operação	get-friends
Descrição	Retorna lista de amigos do usuário.
Requer token?	Sim
Request	Sem corpo
Resposta ok	Array com os dados dos usuários amigos, onde cada usuário é representado por um objeto com os seguintes atributos: id username fullname
Possíveis erros	Nenhum

Operação	remove-friends
Descrição	Desfaz uma amizade. Os usuários não serão mais amigos e, portanto, não poderão conversar mais. Poderão ainda enviar pedidos de amizade entre si.
Requer token?	Sim
Request	friendId
Resposta ok	Sem corpo
Possíveis erros	Nenhum. Não importa se o usuário nem era amigo em primeiro lugar, o resultado final é o mesmo (não são amigos), então nesse caso não consideramos erro.

Requests para manter arquivos

Operação	put-file
Descrição	Envia um arquivo para ficar armazenado no servidor. Não é uma ação que o usuário vai causar diretamente. Quando ele envia uma mensagem com áudio, primeiro o áudio tem que ser armazenado num arquivo no servidor por meio dessa operação e depois a mensagem tem que ser enviada com uma referência a esse arquivo.
Requer token?	Sim
Request	O corpo é o conteúdo binário do arquivo.
Resposta ok	filename Nome do arquivo no servidor (UUID aleatório). Usado para referenciar na mensagem. Inclui extensão.
Possíveis erros	MISSING_FILE_EXTENSION_HEADER IO_ERROR

Operação	get-file
Descrição	Busca o conteúdo binário de um arquivo armazenado no servidor.
Requer token?	Sim
Request	filename Nome do arquivo no servidor.
Resposta ok	Conteúdo binário do arquivo.
Possíveis erros	FILE_DOES_NOT_EXIST IO_ERROR

Requests para manter mensagens

Operação	send-message
Descrição	Envia uma mensagem a um amigo.
Requer token?	Sim
Request	Somente textContents ou fileReference deve estar presente. Ou seja, a mensagem ou contém texto ou contém um arquivo. to ID do usuário destinatário. textContents Conteúdo da Mensagem. fileReference Nome do arquivo.
Resposta ok	id ID da mensagem. sentAt Timestamp em que a mensagem foi enviada.
Possíveis erros	MALFORMED_MESSAGE Quando não segue a regra de que textContents ou fileReference deve estar presente. NOT_FRIENDS Quando o usuário destinatário não é amigo de quem enviou. INTERNAL

Operação	get-messages
Descrição	Busca as mensagens trocadas com um amigo. Não retorna todas, porque seriam muitas, usando paginação no lugar. Mas a paginação também não é por páginas numeradas: deve ser informadas quantas mensagens pegar antes de uma mensagem dada.
Requer token?	Sim
Request	friendId ID do usuário amigo. before ID da mensagem a partir da qual a busca deve ser feita, incluindo ela. limit Quantidade de mensagens a trazer.
Resposta ok	Arrary de mensagens trocadas com o amigo, primeiro as mais recentes e depois as mais antigas (ordenadas pelo ID que incrementa monotonicamente). id ID da mensagem. userId ID do usuário que enviou a mensagem (você ou o amigo). sentAt Timestamp em que a mensagem foi enviada. textContents fileReference
Possíveis erros	NOT_FRIENDS Quando o usuário informado não é seu amigo.

Requests para receber notificações do servidor

Operação	go-online
Descrição	Inicia uma conexão com o servidor por onde ele envia notificações de atualizações (usuário ficou online/offline, usuário enviou mensagem).Essa conexão é mantida pelo socket com que a request foi feita, que é mantido aberto.
Requer token?	Sim
Request	Sem corpo
Resposta ok	Corpo vazio, mas eventualmente envia mensagens de notificação. Todas as mensagens são compostas pelo número de bytes no corpo e pelo corpo, em sequência, sem espaços no meio. O corpo vem em formato JSON. Sempre há um campo type descrevendo o tipo da mensagem. Os valores possíveis são user-online, user-offline, chat-message-received e ping. A mensagem de tipo ping serve para que o servidor detecte quando usuários ficam offline - se o cliente não responder com a string pong a tempo, o servidor desliga a conexão.
Possíveis erros	Sem erros possívels

Operação	go-offline
Descrição	Fecha uma conexão de notificações com o servidor (conexão aberta previamente com go-online). A request não precisa ser enviada com o mesmo socket utilizado para enviar a go-online.
Requer token?	Sim
Request	Sem corpo
Resposta ok	Sem corpo
Possíveis erros	Sem erros possívels

Operação	get-online-users
Descrição	Recebe lista completa dos IDs dos usuários que atualmente estão online. Para que o cliente mantenha a lista de usuários atualmente online atualizadas, primeira envia essa request para receber uma lista inicial, e ao longo do tempo recebe notificações de usuários que ficaram online ou offline pela conexão aberta pela request de go-online.
Requer token?	Sim
Request	Sem corpo
Resposta ok	Array JSON de IDs dos usuários.
Possíveis erros	Sem erros possívels