Messaging services

Questions

Should entities be allowed to have more than one associated message thread? 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?
- This will prevent unreasonable sending-lag and make it possible (if we want) to have real time chat.
- Sending messages to non-principals (i.e. commenting on an entity) does not need asynchronous processing
What ACCESS_TYPE should be associated with the ability to comment on an entity?
- For now, I'm using the SEND_MESSAGE type.
What ACCESS_TYPE should be associated with the ability to message a user?
- For now, there is no restriction
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
- The worker cannot rely on Amazon SQS and the ChangeMessage objects (Processed messages are reprocessed after migration, which is not ideal for notifications)
How should we bounce messages? Silently? Via an auto-generated message?

Objects

Name	DBO	DTO
UserMessage	Primary key: Message ID Key: Thread ID Foreign key: CreatedBy (UserGroup) RecipientType (string) Recipients (gzip-blob) Subject S3 File Handle CreatedOn	ID (derived from ID generator) Thread ID (optional or derived from ID generator) Seems like this field can be hidden, instead users supply a replyTo parameter/field, which fills in this value To (RecipientBundle) Subject (string) Message Body (string, no attachments) CreatedOn CreatedBy (principal ID) (upon creation filled in for the authenticated user)
Message Status	Foreign key: Message ID Foreign key: Recipient ID (UserGroup) States: UNREAD, READ, ARCHIVED	ID Recipient State
Node Messages	Foreign key: Thread ID Foreign key: Node ID	N/A
Message Settings	Foreign key: User ID (UserGroup) 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	N/A	Bundles the User Message and Message Status
RecipientBundle	N/A	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
- 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 with respect to message creation.

Services

Note: services that return paginated results are assumed to have limit and offset parameters

Method	URI	Body	Parameters	Return	Description	Permission
GET	/message/inbox		orderBy=sendDate descending=true	Paginated results<MessageBundle>	Gets all messages the authenticated user has received	Authenticated User
GET	/message/outbox		orderBy=sendDate descending=true	Paginated results<UserMessage>	Gets all messages the authenticated user has sent	Authenticated User
POST	/message	UserMessage	replyTo=null (i.e. another 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/{id}/forward	RecipientBundle			Forwards a message to other recipients. This is equivalent to getting a (visible) message and POST-ing it to /message
POST	/entity/{id}/comments	UserMessage			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}			UserMessage	Gets a specific message	Sender or Receiver
GET	/message/{id}/thread		orderBy=sendDate descending=true	Paginated results<UserMessage>	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		orderBy=sendDate descending=true	Paginated results<UserMessage>	Gets message belonging to the thread tied to the entity.	Authenticated user with READ permission on entity
GET	/message/{id}/status			Message Status	Gets the status of a message	Receiver
PUT	/message/{id}/status	Message Status			Marks a message as: READ UNREAD ARCHIVED	Receiver
GET	/message/settings			Message Settings	Gets the notification settings of the user	Authenticated User
PUT	/message/settings	Message Settings			Changes notification settings	Authenticated User