gergely/taskwarrior-2.x
1
0
Fork 0
Code Issues Actions Packages Projects Releases 1 Wiki Activity

reformat to one sentence per line

Browse Source
This commit is contained in:
Dustin J. Mitchell
2022-04-21 01:15:17 +00:00
committed by Tomas Babej
parent ade706a72e
commit b1ca5d4cf8
17 changed files with 842 additions and 1052 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
docs/rfcs/request.md
View File

@@ -2,41 +2,29 @@
title: "Taskwarrior - Request"
---
# Taskserver Message Format
The Taskserver accepts and emits only messages. These messages look somewhat
like email, as defined in [RFC821](https://tools.ietf.org/html/rfc821),
[RFC2822](https://tools.ietf.org/html/rfc2822).
The message format allows for data, metadata, and extensibility. This
combination allows the Taskserver to accommodate current and future needs. This
document describes the message format, and the supported message types.
The Taskserver accepts and emits only messages.
These messages look somewhat like email, as defined in [RFC821](https://tools.ietf.org/html/rfc821), [RFC2822](https://tools.ietf.org/html/rfc2822).
The message format allows for data, metadata, and extensibility.
This combination allows the Taskserver to accommodate current and future needs.
This document describes the message format, and the supported message types.
## Requirements
In this document, we adopt the convention discussed in Section 1.3.2 of
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
significance of each particular requirement specified in this document.
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
may exist valid reasons for ignoring this item, but the full implications should
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
item is optional, and may be omitted without careful consideration.
In this document, we adopt the convention discussed in Section 1.3.2 of [RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the significance of each particular requirement specified in this document.
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there may exist valid reasons for ignoring this item, but the full implications should be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this item is optional, and may be omitted without careful consideration.
## Encoding
All messages are UTF8-encoded text.
## Message Format
This format is based on [RFC2822](https://tools.ietf.org/html/rfc2822),
\'Internet Message Format\'. Here is an example of the format:
This format is based on [RFC2822](https://tools.ietf.org/html/rfc2822), \'Internet Message Format\'.
Here is an example of the format:
<SIZE>
name: value
@@ -44,22 +32,21 @@ This format is based on [RFC2822](https://tools.ietf.org/html/rfc2822),
payload
There are three sections. The first is the size, which is a 4-byte, big- Endian,
binary byte count of the length of the message, including the 4 bytes for the
size.
There are three sections.
The first is the size, which is a 4-byte, big- Endian, binary byte count of the length of the message, including the 4 bytes for the size.
The header section is a set of name/value pairs separated by newline characters
(U+000D). The name is separated from the value by \': \' (colon U+003A, space
U+0020) The header section is terminated by two consecutive newline (U+000D)
characters. All text is UTF8-encoded.
The header section is a set of name/value pairs separated by newline characters (U+000D).
The name is separated from the value by \': \' (colon U+003A, space U+0020) The header section is terminated by two consecutive newline (U+000D) characters.
All text is UTF8-encoded.
The payload section is arbitrary, and message type-specific. However, it is
still UTF8-encoded text.
The payload section is arbitrary, and message type-specific.
However, it is still UTF8-encoded text.
## Message Requirements
Messages SHALL contain particular headers. Those are:
Messages SHALL contain particular headers.
Those are:
- type
- protocol
@@ -67,13 +54,11 @@ Messages SHALL contain particular headers. Those are:
The \'type\' value is what determines the interpretation of the payload.
The \'protocol\' value should be \'v1\', or any subsequently published protocol
version.
The \'protocol\' value should be \'v1\', or any subsequently published protocol version.
The \'client\' represent the client identifier, so that any special cases can be
handled. For example, an emergency fix that is client version-specific could be
released, to support users that have not updated their client, or perhaps the
client has not released a fix. The form of the \'version\' value is:
The \'client\' represent the client identifier, so that any special cases can be handled.
For example, an emergency fix that is client version-specific could be released, to support users that have not updated their client, or perhaps the client has not released a fix.
The form of the \'version\' value is:
<product identifier> <version number>
@@ -81,14 +66,13 @@ As an example:
taskwarrior 2.3.0
DO NOT spoof any other software using this client value. If another client is
spoofed, then patches addressing protocol errors may break working software.
DO NOT spoof any other software using this client value.
If another client is spoofed, then patches addressing protocol errors may break working software.
## Auth Data
Every request from the client SHALL contain \"auth\" information, which involves
these header entries:
Every request from the client SHALL contain \"auth\" information, which involves these header entries:
org: <organization>
user: <user>
@@ -96,8 +80,8 @@ these header entries:
The user and org fields uniquely identify a user.
The key field is generated when a new server account is set up. It is a shared
secret, equivalent to a password, and should be protected.
The key field is generated when a new server account is set up.
It is a shared secret, equivalent to a password, and should be protected.
Authentication failure can result in these errors:
@@ -112,30 +96,26 @@ Every response from the Taskserver SHALL contain status data:
code: <code>
status: <status text>
The code is a numeric status indicator defined in the [Sync
Protocol](/docs/design/protocol).
The code is a numeric status indicator defined in the [Sync Protocol](/docs/design/protocol).
## Payload Data
Payload data is optional, arbitrary and message type dependent. It is always
UTF8-encoded text.
Payload data is optional, arbitrary and message type dependent.
It is always UTF8-encoded text.
## Message Types
The Taskserver supports several message types, thus providing a set of
primitives for use by clients.
The Taskserver supports several message types, thus providing a set of primitives for use by clients.
It is expected that the number of supported ticket types will increase over
time.
It is expected that the number of supported ticket types will increase over time.
## Sync Message
The \"sync\" message always originates from the client, but the response will
contain data from the server. A sync is therefore a single request with a single
response.
The \"sync\" message always originates from the client, but the response will contain data from the server.
A sync is therefore a single request with a single response.
The \"sync\" message type MUST contain the following headers:
@@ -166,9 +146,7 @@ Here is an example of a sync message:
2e4685f8-34bc-4f9b-b7ed-399388e182e1
{"description":"Test data","entry":"20130602T002341Z","status":"pending"}
The request contains the proper auth section, and the body contains the current
sync key followed by a newline characters (U+000D), then a list of
JSON-formatted tasks \[2\] each separated by a newline character (U+000D).
The request contains the proper auth section, and the body contains the current sync key followed by a newline characters (U+000D), then a list of JSON-formatted tasks \[2\] each separated by a newline character (U+000D).
An example response message might be:
@@ -180,8 +158,7 @@ An example response message might be:
45da7110-1bcc-4318-d33e-12267a774e0f
The status indicates success, and the payload contains zero remote task
modifications, followed by a sync key.
The status indicates success, and the payload contains zero remote task modifications, followed by a sync key.
## Statistics Message
@@ -195,7 +172,8 @@ The message format іs simply:
client: taskd 1.0.0
protocol: v1
There is no payload. An example response message might be:
There is no payload.
An example response message might be:
<size>type: response
client: taskd 1.0.0
@@ -216,6 +194,5 @@ There is no payload. An example response message might be:
There is no payload, and the results are in the header variables.
Note that the statistics gathered by the server are growing, which means new
values are occasionally added to the response message. Existing values will not
be removed.
Note that the statistics gathered by the server are growing, which means new values are occasionally added to the response message.
Existing values will not be removed.