From 00e929afac88174dfaf7fdf9e118939d77a6e3e0 Mon Sep 17 00:00:00 2001 From: "B. Petersen" Date: Wed, 18 Sep 2019 14:39:58 +0200 Subject: [PATCH] reformat: use shorter lines (max. 80 chats) and try to add linebreaks semantically --- spec.md | 180 ++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 122 insertions(+), 58 deletions(-) diff --git a/spec.md b/spec.md index a34cd969a..488d0a3a6 100644 --- a/spec.md +++ b/spec.md @@ -2,7 +2,9 @@ Version 0.19.0 -This document describes how emails can be used to implement typical messenger functions while staying compatible to existing MUAs. +This document describes how emails can be used +to implement typical messenger functions +while staying compatible to existing MUAs. - [Encryption](#encryption) - [Outgoing messages](#outgoing-messages) @@ -20,10 +22,14 @@ This document describes how emails can be used to implement typical messenger fu # Encryption -Messages SHOULD be encrypted by the [Autocrypt](https://autocrypt.org/level1.html) standard; `prefer-encrypt=mutual` MAY be set by default. +Messages SHOULD be encrypted by the +[Autocrypt](https://autocrypt.org/level1.html) standard; +`prefer-encrypt=mutual` MAY be set by default. -Meta data (at least the subject and all chat-headers) SHOULD be encrypted by the [Memoryhole](https://github.com/autocrypt/memoryhole) standard. -If Memoryhole is not used, the subject of encrypted messages SHOULD be replaced by the string +Meta data (at least the subject and all chat-headers) SHOULD be encrypted +by the [Memoryhole](https://github.com/autocrypt/memoryhole) standard. +If Memoryhole is not used, +the subject of encrypted messages SHOULD be replaced by the string `Chat: Encrypted message` where the part after the colon MAY be localized. @@ -31,7 +37,8 @@ If Memoryhole is not used, the subject of encrypted messages SHOULD be replaced Messengers MUST add a `Chat-Version: 1.0` header to outgoing messages. For filtering and smart appearance of the messages in normal MUAs, -the `Subject` header SHOULD start with the characters `Chat:` and SHOULD be an excerpt of the message. +the `Subject` header SHOULD start with the characters `Chat:` +and SHOULD be an excerpt of the message. Replies to messages MAY follow the typical `Re:`-format. The body MAY contain text which MUST have the content type `text/plain` @@ -41,8 +48,8 @@ The text MAY be divided into a user-text-part and a footer-part using the line `-- ` (minus, minus, space, lineend). The user-text-part MUST contain only user generated content. -User generated content are eg. texts a user has actually typed or pasted or -forwarded from another user. +User generated content are eg. texts a user has actually typed +or pasted or forwarded from another user. Full quotes, footers or sth. like that MUST NOT go to the user-text-part. From: sender@domain @@ -56,14 +63,19 @@ Full quotes, footers or sth. like that MUST NOT go to the user-text-part. # Incoming messages -The `Chat-Version` header MAY be used to detect if a messages comes from a compatible messenger. +The `Chat-Version` header MAY be used +to detect if a messages comes from a compatible messenger. -The `Subject` header MUST NOT be used to detect compatible messengers, groups or whatever. +The `Subject` header MUST NOT be used +to detect compatible messengers, groups or whatever. -Messenger SHOULD show the `Subject` if the message comes from a normal MUA together with the email-body. -The email-body SHOULD be converted to plain text, full-quotes and similar regions SHOULD be cut. +Messenger SHOULD show the `Subject` +if the message comes from a normal MUA together with the email-body. +The email-body SHOULD be converted +to plain text, full-quotes and similar regions SHOULD be cut. -Attachments SHOULD be shown where possible. If an attachment cannot be shown, a non-distracting warning SHOULD be printed. +Attachments SHOULD be shown where possible. +If an attachment cannot be shown, a non-distracting warning SHOULD be printed. # Forwarded messages @@ -90,21 +102,25 @@ which SHOULD be anonymized or just a placeholder. Hello world! Incoming forwarded messages are detected by the header. -The messenger SHOULD mark these messages in a way that it becomes obvious -that the message is not created by the sender. -Note that most messengers do not show the original sender with forwarded messages +The messenger SHOULD mark these messages in a way that +it becomes obvious that the message is not created by the sender. +Note that most messengers do not show the original sender of forwarded messages but MUAs typically expose the sender in the UI. # Groups -Groups are chats with usually more than one recipient, each defined by an email-address. +Groups are chats with usually more than one recipient, +each defined by an email-address. The sender plus the recipients are the group members. -To allow different groups with the same members, groups are identified by a group-id. -The group-id MUST be created only from the characters `0`-`9`, `A`-`Z`, `a`-`z` `_` and `-`. +To allow different groups with the same members, +groups are identified by a group-id. +The group-id MUST be created only from the characters +`0`-`9`, `A`-`Z`, `a`-`z` `_` and `-`. -Groups MUST have a group-name. The group-name is any non-zero-length UTF-8 string. +Groups MUST have a group-name. +The group-name is any non-zero-length UTF-8 string. Groups MAY have a group-image. @@ -113,13 +129,17 @@ Groups MAY have a group-image. All group members MUST be added to the `From`/`To` headers. The group-id MUST be written to the `Chat-Group-ID` header. -The group-name MUST be written to `Chat-Group-Name` header (the forced presence of this header makes it easier to join a group chat on a second device any time). +The group-name MUST be written to `Chat-Group-Name` header +(the forced presence of this header makes it easier +to join a group chat on a second device any time). -The `Subject` header of outgoing group messages SHOULD start with the characters `Chat:` followed by the group-name and a colon followed by an excerpt of the message. +The `Subject` header of outgoing group messages +SHOULD start with the characters `Chat:` +followed by the group-name and a colon followed by an excerpt of the message. -To identify the group-id on replies from normal MUAs, the group-id MUST also be added to -the message-id of outgoing messages. The message-id MUST have the -format `Gr..`. +To identify the group-id on replies from normal MUAs, +the group-id MUST also be added to the message-id of outgoing messages. +The message-id MUST have the format `Gr..`. From: member1@domain To: member2@domain, member3@domain @@ -131,30 +151,46 @@ format `Gr..`. Hello group - this group contains three members -Messengers adding the member list in the form `Name ` MUST take care only to spread the names authorized by the contacts themselves. -Otherwise, names as _Daddy_ or _Honey_ may be spread (this issue is also true for normal MUAs, however, for more contact- and chat-centralized apps +Messengers adding the member list in the form `Name ` +MUST take care only to spread the names authorized by the contacts themselves. +Otherwise, names as _Daddy_ or _Honey_ may be spread +(this issue is also true for normal MUAs, however, +for more contact- and chat-centralized apps such situations happen more frequently). ## Incoming group messages -The messenger MUST search incoming messages for the group-id in the following headers: `Chat-Group-ID`, +The messenger MUST search incoming messages for the group-id +in the following headers: `Chat-Group-ID`, `Message-ID`, `In-Reply-To` and `References` (in this order). -If the messenger finds a valid and existent group-id, the message SHOULD be assigned to the given group. -If the messenger finds a valid but not existent group-id, the messenger MAY create a new group. -If no group-id is found, the message MAY be assigned to a normal single-user chat with the email-address given in `From`. +If the messenger finds a valid and existent group-id, +the message SHOULD be assigned to the given group. +If the messenger finds a valid but not existent group-id, +the messenger MAY create a new group. +If no group-id is found, +the message MAY be assigned +to a normal single-user chat with the email-address given in `From`. ## Add and remove members -Messenger clients MUST construct the member list from the `From`/`To` headers only on the first group message or if they see a `Chat-Group-Member-Added` or `Chat-Group-Member-Removed` action header. -Both headers MUST have the email-address of the added or removed member as the value. -Messenger clients MUST NOT construct the member list on other group messages (this is to avoid accidentally altered To-lists in normal MUAs; the user -does not expect adding a user to a _message_ will also add him to the _group_ "forever"). +Messenger clients MUST construct the member list +from the `From`/`To` headers only on the first group message +or if they see a `Chat-Group-Member-Added` +or `Chat-Group-Member-Removed` action header. +Both headers MUST have the email-address +of the added or removed member as the value. +Messenger clients MUST NOT construct the member list +on other group messages +(this is to avoid accidentally altered To-lists in normal MUAs; +the user does not expect adding a user to a _message_ +will also add him to the _group_ "forever"). The messenger SHOULD send an explicit mail for each added or removed member. -The body of the message SHOULD contain a localized description about what happened +The body of the message SHOULD contain +a localized description about what happened and the message SHOULD appear as a message or action from the sender. From: member1@domain @@ -190,7 +226,8 @@ with the value set to the old group name to all group members. The new group name goes to the header `Chat-Group-Name`. The messenger SHOULD send an explicit mail for each name change. -The body of the message SHOULD contain a localized description about what happened +The body of the message SHOULD contain +a localized description about what happened and the message SHOULD appear as a message or action from the sender. From: member1@domain @@ -208,13 +245,17 @@ and the message SHOULD appear as a message or action from the sender. ## Set group image A group MAY have a group-image. -To change or set the group-image, the messenger MUST attach an image file to a message and MUST add the header `Chat-Group-Image` with the -value set to the image name. +To change or set the group-image, +the messenger MUST attach an image file to a message +and MUST add the header `Chat-Group-Image` +with the value set to the image name. -To remove the group-image, the messenger MUST add the header `Chat-Group-Image: 0`. +To remove the group-image, +the messenger MUST add the header `Chat-Group-Image: 0`. The messenger SHOULD send an explicit mail for each group image change. -The body of the message SHOULD contain a localized description about what happened +The body of the message SHOULD contain +a localized description about what happened and the message SHOULD appear as a message or action from the sender. @@ -239,20 +280,29 @@ and the message SHOULD appear as a message or action from the sender. /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBw ... --==break==-- -The image format SHOULD be image/jpeg or image/png. To save data, it is RECOMMENDED to add a `Chat-Group-Image` only on image changes. +The image format SHOULD be image/jpeg or image/png. +To save data, it is RECOMMENDED +to add a `Chat-Group-Image` only on image changes. # Set profile image A user MAY have a profile-image that MAY be spread to his contacts. -To change or set the profile-image, the messenger MUST attach an image file to a message and MUST add the header `Chat-Profile-Image` with the -value set to the image name. +To change or set the profile-image, +the messenger MUST attach an image file to a message +and MUST add the header `Chat-Profile-Image` +with the value set to the image name. -To remove the profile-image, the messenger MUST add the header `Chat-Profile-Image: 0`. +To remove the profile-image, +the messenger MUST add the header `Chat-Profile-Image: 0`. -To spread the image, the messenger MAY send the profile image together with the next mail to a given contact -(to do this only once, the messenger has to keep a `profile_image_update_state` somewhere). -Alternatively, the messenger MAY send an explicit mail for each profile-image change to all contacts using a compatible messenger. +To spread the image, +the messenger MAY send the profile image +together with the next mail to a given contact +(to do this only once, +the messenger has to keep a `profile_image_update_state` somewhere). +Alternatively, the messenger MAY send an explicit mail +for each profile-image change to all contacts using a compatible messenger. The messenger SHOULD NOT send an explicit mail to normal MUAs. From: sender@domain @@ -273,18 +323,25 @@ The messenger SHOULD NOT send an explicit mail to normal MUAs. AKCgkJi3j4l5kjoldfUAKCgkJi3j4lldfHjgWICwgIEBQYFBA ... --==break==-- -The image format SHOULD be image/jpeg or image/png. Note that `Chat-Profile-Image` may appear together with all other headers, eg. there may be a -`Chat-Profile-Image` and a `Chat-Group-Image` header in the same message. To save data, it is RECOMMENDED to add a `Chat-Profile-Image` header only on image changes. +The image format SHOULD be image/jpeg or image/png. +Note that `Chat-Profile-Image` may appear together with all other headers, +eg. there may be a `Chat-Profile-Image` and a `Chat-Group-Image` header +in the same message. +To save data, it is RECOMMENDED to add a `Chat-Profile-Image` header +only on image changes. # Miscellaneous -Messengers SHOULD use the header `Chat-Predecessor` instead of `In-Reply-To` as -the latter one results in infinite threads on typical MUAs. +Messengers SHOULD use the header `Chat-Predecessor` +instead of `In-Reply-To` as the latter one results +in infinite threads on typical MUAs. -Messengers SHOULD add a `Chat-Voice-message: 1` header if an attached audio file is a voice message. +Messengers SHOULD add a `Chat-Voice-message: 1` header +if an attached audio file is a voice message. -Messengers MAY add a `Chat-Duration` header to specify the duration of attached audio or video files. +Messengers MAY add a `Chat-Duration` header +to specify the duration of attached audio or video files. The value MUST be the duration in milliseconds. This allows the receiver to show the time without knowing the file format. @@ -292,16 +349,23 @@ This allows the receiver to show the time without knowing the file format. Chat-Voice-Message: 1 Chat-Duration: 10000 -Messengers MAY send and receive Message Disposition Notifications (MDNs, [RFC 8098](https://tools.ietf.org/html/rfc8098), [RFC 3503](https://tools.ietf.org/html/rfc3503)) -using the `Chat-Disposition-Notification-To` header instead of the `Disposition-Notification-To` (which unfortunately forces many other MUAs to send weird mails not following any -standard). +Messengers MAY send and receive Message Disposition Notifications +(MDNs, [RFC 8098](https://tools.ietf.org/html/rfc8098), +[RFC 3503](https://tools.ietf.org/html/rfc3503)) +using the `Chat-Disposition-Notification-To` header +instead of the `Disposition-Notification-To` +(which unfortunately forces many other MUAs +to send weird mails not following any standard). ## Sync messages -If some action is required by a message header, the action should only be performed if the _effective date_ is newer than the date the last action was performed. +If some action is required by a message header, +the action should only be performed if the _effective date_ is newer +than the date the last action was performed. -We define the effective date of a message as the sending time of the message as indicated by its Date header, +We define the effective date of a message +as the sending time of the message as indicated by its Date header, or the time of first receipt if that date is in the future or unavailable.