Messaging services

Questions

Should entities be allowed to have more than one associated message thread?
- A: Yes. A "thread" is just a linked list of messages, linked by their inReplyTo reference, which is optional. The ID of the thread is just the ID of the first message in the list, which has an empty 'inReplyTo' field. So if more than one message is 'sent to' an entity (as part of a discussion forum) with an empty inReplyTo field, then there is more than one thread for the entity.
Or message threads to have more than one associated entity?
Should we allow messages to be sent to multiple non-principals at once?
Should messages with low numbers of recipients be processed in an immediately consistent manner?
- Sending messages to non-principals (i.e. commenting on an entity) does not need asynchronous processing
- Sending messages to a single recipient will be done transactionally
What ACCESS_TYPE should be associated with the ability to comment on an entity?
- SEND_MESSAGE
What ACCESS_TYPE should be associated with the ability to message a user?
- No restriction
- Add a blacklist
- Flag as inappropriate
Should the worker use SQS or RDS to manage the flow of messages to send?
- Proposed RDS implementation:
  - Add a migratable table with a single column of message IDs
  - Add a worker that periodically polls the table
  - If the table is not empty, process N rows from the top
  - Delete rows once finished processing
- Using SQS opens up the possibility of losing messages (especially during weekend stack switching). The state stored in SQS would not be migrated between stacks. And unlike change messages, there is no trivial method to detect if a message has been changed. And reusing the change messages is not possible, since retransmission of messages is incorrect behavior.
How should we bounce messages? Silently? Via an auto-generated message?
- Add services to check if message can be sent. This way, the UI can check if a message can be sent before sending it.
- On an error, send an error message to the sender's inbox.
How should we handle messages sent to groups rather than individuals? Should the message be broken into individuals messages (after checking for SEND_MESSAGE permission on the group)?
- Currently, it simply stashes the message, leaving no way of fetching the message (other than as a sender).

Objects

Name	DBO	Migration	DTO
MessageContent (Immutable after creation)	Primary key: ID Foreign key: CreatedBy (UserGroup) Foreign key: MessageBody (S3 File Handle ID) Self foreign key: InReplyTo (ID) (nullable) Etag CreatedOn	Backup via ID Note: Etag is required because MessageStatus is mutable.	Interface ID CreatedBy (principal ID) S3 File Handle ID inReplyTo (optional) CreatedOn
MessageToUser (Immutable after creation)	Foreign key: ID (MessageContent) Subject (nullable)	Secondary to MessageContent	Implements MessageContent Subject (string, optional) List of recipient IDs
MessageRecipient (Immutable after creation)	Foreign key: ID (MessageContent) Foreign key: Recipient ID (UserGroup)	Secondary to MessageContent
MessageStatus	Foreign key: ID (MessageContent) Foreign key: Recipient ID (UserGroup) States: UNREAD, READ, ARCHIVED	Secondary to MessageContent	ID Recipient State
Comment (Immutable after creation)	Foreign key: ID (MessageContent) Target type (Enum ObjectType) Target ID	Secondary to MessageContent	Implements MessageContent Target type Target ID
MessageInReplyToRoot (Immutable after creation)	Primary key: MessageContentID (FK to MessageContent) Foreign key: InReplyToRootID Recursive foreign key to primary key	Secondary to MessageContent	n/a
Message votes	Primary key: Message ID Up votes Down votes		ID Up Down
MessageSettings	Foreign key: User ID (UserGroup) Etag Blob of settings		ID Notification levels Update to an owned entity Update to some favorite entity Team Message from user Mail to everyone Etc... Message receipt email (if more than one) Auto-mark mail as read if forwarded to email
MessageBundle			Bundles the Message and Message Status
RecipientBundle			RecipientType May be a principal, entity, ... Array of IDs All IDs must be valid (404 otherwise)

Other

Message ID generator
Thread ID generator
Email mechanism
- Use Amazon SES
  - Since we've decided to use SES, we should use their REST API rather than their SMTP API.
  - The Gmail server may be useful for handling bounced messages.
  - This will make the following two mocking methods impossible:
    - Mocking javax mail: http://ollivander.franzoni.eu/2011/08/30/mock-javamail-primer/
    - Mocking an SMTP server: http://quintanasoft.com/dumbster/
Message delivery will be via worker, i.e. asynchronous (in most cases) with respect to message creation.

Services

Sort by recipient

Method	URI	underlying query (if any)	Body	Parameters	Return	Description	Permission
GET	/message/inbox	select * from messagecontent c, messagetouser m, messagestatus s where c.ID=m.messageContentID and s.messageContentID=c.ID and s.recipientID=<pid>		Sorting + pagination	Paginated results<MessageBundle>	Gets all messages the authenticated user has received	Authenticated User
GET	/message/outbox	select * from messagecontent c, messagetouser m where c.ID=m.messageContentID and c.createdBy=<pid> TODO: what is the best way to populate the recipients?		Sorting + pagination	Paginated results<Message>	Gets all messages the authenticated user has sent	Authenticated User
POST	/message	n/a	Message	inReplyTo=null (i.e. another Message)	Message	Sends a message. Note, message delivery permission is on a recipient-by-recipient basis, asynchronous to the message creation. Unauthorized delivery may result in silent failure or a bounce message (TBD).	Authenticated User Must be admin to send to AUTH_USERS
POST	/message/check	use existing userGroupDAO query to check recipients.	Message	inReplyTo=null (i.e. another Message)	Boolean ErrorResponse	Checks to see if the message is correctly formatted and that the sender has permission to send to the indicated recipients	Authenticated User
POST	/message/{id}/forward	n/a	RecipientBundle			Forwards a message to other recipients. This is equivalent to getting a (visible) message and POST-ing it to /message	Sender or Receiver
POST	/entity/{id}/comments	n/a	Message		Message	Convenience method for commenting on an entity. The service fills out fields like message ID, thread ID, and recipients, leaving just subject and body for the user.	Authenticated user with SEND_MESSAGE permission on entity
GET	/message/{id}	select * from messagecontent c, messagetouser m where c.ID=m.messageContentID and c.ID=<id>			Message	Gets a specific message	Sender or Receiver
GET	/message/{id}/conversation	TODO		Sorting + pagination	Paginated results<Message>	Gets messages belonging in the same thread as the message ID. The list is filtered according to the user's ID.	Sender or Receiver
GET	/entity/{id}/comments	select * from messagecontent mc, comment c, inreploytoroot r where mc.ID=c.messageContentID and c.TargetType='ENTITY" and c.TargetID=<id>		Sorting + pagination	Paginated results<Message>	Gets message belonging to the thread tied to the entity.	Authenticated user with READ permission on entity
GET	/message/{id}/status	select * from messagestatus where messagstatus.messageContentID=<id>			Message Status	Gets the status of a message	Receiver
PUT	/message/status	n/a	MessageStatus			Marks a message as: READ UNREAD ARCHIVED	Receiver
GET	/message/settings	TODO			MessageSettings	Gets the notification settings of the user	Authenticated User
PUT	/message/settings	TODO	MessageSettings			Changes notification settings	Authenticated User

'* 'replyTo' is a misnomer. In email 'replyTo' is the address of the person to whom you send an email reply. In this case it's the ID of the message referenced by the current message. So it should be called 'inReplyTo' or some other distinctive name.