Project Stage 1

Project Stage 1#

Network Protocol Specification#

Write an RFC-Style specification of the protocol with which chat clients and servers communicate. The document should be a PDF, in an 11-point font size for the smallest kind of text, of at most 12 pages.

Formalities#

You need to submit the PDF in Canvas by 5pm on Friday, 25 September. No late submissions without extensions will be accepted.

Groups#

You may do this assignment alone or in a group of up to 5 students. All students in a group must be enroled in COMP1140. If you work in a group, you must to produce the document together in one or more live meetings. Everyone in the group is responsible and must understand every line of the document. The purpose of working together is to include more perspectives and thus have a better chance to think of various corner cases, not to divide up work.

To submit as a group, you have to have a draft document written by the week 7 workshop (i.e. Tuesday, 22 September). The draft must feature the names and UIDs of everyone who participated in the creation of it, and specifically list sufficient individual contributions from everyone. Your whole group must come to me before the workshop (modulo excuses due to illness, in which case you need to send me an e-mail before the workshop), and hand me a copy of the draft (either as a print-out or as an e-mailed PDF). I will confirm the groups on the evening on that day, and create them in Canvas so you can submit as a group. If you do not get a confirmation e-mail for your group by 23:59, Tuesday, 22 September, you must create your own document. You can base the document on your own listed contributions to any group document that was rejected. You are in any case expected to have invested a significant enough amount of thinking time into this to be able to write up a document relatively quickly, even if this happens. Do not wait to start working on this until week 7.

License#

By default, by submitting this assignment, you grant us a license to publish it here in either its original form or with changes made by us, as part of a specification for the rest of the assignment, in the case that your submission gets chosen as the specification. Your contributions will be attributed to you. You may object to either the attribution or the publication, by stating this at the start of your document. In case you object to the publication, your submission will not be eligible to be chosen to form the specification for the rest of the assignment, but will still be marked normally.

If you work as a group, any member of the group may object to attribution or publication, which for attribution is individual, but for publication will affect the whole group’s submission. Discuss any potential objections early on when forming a group. For a group submission, objections for the draft submitted at the week 7 workshop and the final version are separate. You need to include any objections to attribution or publication for the draft version, and anyone can change their opinion on attribution or publication for the final version. In case a member of a group did not object to publication for the draft version but does so for the final version, the group may try to submit a second final version that excludes contributions by that group member since the draft version, which would be eligible for selection and publication; the full group final version would be the one that is marked.

In summary:

• If you don’t want your submission to be used as the standard: Object publication by stating this at the start of your document
• If you don’t want your name on the submission if your standard is chosen: Object attribution by stating this at the start of your document

Backup and Flexibility#

While we aim to (at least largely) use one of your submitted specifications for the rest of the project, we may decide to use our own. In either case, the specification will not be completely set in stone. As we discover new corner cases or other difficulties, or if we decide to add extensions later on, we may adjust the specification during the course of the project. We invite you to actively participate in workshop discussions and on the Ed Class forum to provide input on any necessary or otherwise desirable changes.

Structure#

Your specification should focus on the networking protocol, specifically:

• The format of messages
• Who should send what messages and when
• How to handle various kinds of errors and special cases

It should be clear from your document how the entire lifecycle of a client-server connection, from initialisation to an orderly disconnect, and all the messages in between, would work, such that if two different people would implement the client and the server without talking to teach other, just looking at the document, the resulting combination would work just fine.

It should be clear what the expectations are of the server and the client, in the sense that the other side may protect itself and terminate the connection if said expectations are not met.

You should keep the protocol relatively simple, and try to make it such that for any potential action, there is a single correct way to express it in the protocol (barring some potential flexibility to help with minor lapses in correctness; that is, a single faulty message should not necessary destroy the ability for the server and client to communicate further). If your protocol allows for certain flexibilities, be sure to make clear what any party must do vs. what any party may do.

You should make sure that your protocol can be extended with new features, so that newer versions of clients and servers can communicate both with each other and with older versions that might not understand all messages in the newer protocol.

You do not need to define your notation for grammars. Refer to the Augmented BNF definition in the HTTP 1.0 RFC - that is, the part in section 2.1 that explains the notation.

Outline and Key Decisions#

Connections and Encoding#

By default, a client should initiate a connection to a server at port 1140. You may specify additional connections (temporary or longer-term) to be made at various other ports (these may also be dynamically determined by the server and communicated to the client) where appropriate. All connections are to be TCP connections, and to be initiated by the client and accepted by the server.

The initial connection should always use UTF-8 as the character encoding. Other connections may use different encodings where appropriate (hint: you may find Base64 useful when transferring some kinds of non-ASCII data).

Versioning#

The protocol must support different levels of implementation/versions. A client and server must detect each other’s version and communicate using the highest version of the protocol supported by both (potentially disabling some features that are technically supported by one side). We specify a few levels of implementation here, the protocol should support extensions to be added later, as new versions. The message format should be such that it would be easy to add new kinds of messages in a typical implementation of an older version. Each version must support all features of a previous version.

It is in principle up to you to decide whether particular message formats change between versions or can be re-used - you could treat the different versions as entirely separate protocols, at least after the version negotiation part. There may be a trade-off between the implementation complexity of advanced clients that support multiple versions and the minimum effort to implement a simpler version. Try to find a good balance.

Key Decisions#

• Data is generally stored on servers. In particular:
  • User database (fixed; should be configurable via some file)
  • Messages and Metadata (at least timestamp, author, and body)
  • Other version-specific data
• Clients may cache some information relevant to their particular user (like a local copy of chat history)
• Clients initiate connection to server
• Clients may have more or less arbitrary user interfaces. May be automated scripts, may be console applications, may be GUI apps.
• For the purposes of the networking protocol, message bodies are just a bunch of text with no specific format (we’ll deal with any sort of special content separately)

Versions#

Version 1 - Basic Chat#

• Clients connect to server and authenticate via username and password hash
• Clients can somehow find out list of users
• Users can send direct messages to other users (and receive said messages)
  • Users may be offline, in which case server stores messages for them and delivers them when they connect via some client
• The protocol should ensure that, given enough time, any user that is currently online and any other user could see the same chat history between them up to the point where the other user was last online (that is, every client should eventually be aware whether sending a message succeeded or not)

Version 2 - Channels#

• Users can create new channels
  • Initially, only the creating user is a member of the new channel
  • Channels exist permanently (though client UIs may offer a feature to hide them)
• Users can add other users to channels of which they are a member
  • Membership is permanent and offers accss to the whole chat history of a channel
• There is a global channel of which every user is a member, they can send to it and see all messages on it
• Messages are sent to specific channels, and have at least an author, a timestamp of when they were sent, and a body of text
  • Direct messages from version 1 should now be seen as particular channels, and there might be multiple channels for direct messages between two people

Version 3 - Metadata#

• Channels have a unique identifier, but may also have a name that any user in them can change
• Users may change their display name (though their username for authentication remains unchanged)
• Users may set a status message
• Such metadata changes are propagated to other clients

Version 4 - Receipts#

• Clients send and receive receipts for a message having been delivered to a client, and for a user having read a message

Version 5 - File Transfer#

• Two clients that are simultaneously online may transfer an arbitrary file from one to the other (the data is transferred via the connections between the clients and the server, but the server never stores that data other than to immediately forward it)

Further Discussion#

The above specification is meant to be at a relatively high level, which hopefully leaves you some room to make your own decisions. Some of those you can just make as part of specifying your protocol, but you may encounter questions that warrant broader discussion. If so, please make use of the Ed Discussion forum (there is a category for the project). You should feel absolutely free to discuss any aspect of the project with any of your classmates. In fact, we highly encourage you to do so.

You will still need to write separate reports beyond the maximum group size, and ultimately, you will need to write the implementations of the server, client library, and client UI yourself. But beyond that, please discuss design decisions, corner cases, and other issues freely and openly. We’ll weigh in where necessary, though we hope that many questions can be resolved among you all as a cohort.

Hint: some of you might want to work with a group, but haven’t had an opportunity to form one in the last workshop. The discussion forum may help you there, too.