mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-06-26 10:54:26 +02:00
971b229a4b
* move doc/misc to top level, add READMEs * Move docs -> doc/devel This also consolidates the _three_ documents describing (differently) how to build Taskwarrior into a signle document.
171 lines
8.1 KiB
Markdown
171 lines
8.1 KiB
Markdown
---
|
|
title: "Taskwarrior - Sync Protocol"
|
|
---
|
|
|
|
|
|
# Sync Protocol
|
|
|
|
|
|
## Introduction
|
|
|
|
Taskwarrior data has typically been shared in several ways.
|
|
Those include SCM (source code management) systems, directory synchronizing software (such as DropBox), and by use of the 'push', 'pull' and 'merge' commands introduced in version 1.9.3.
|
|
|
|
While these methods work, they each have problems associated with the merging of data.
|
|
In the case of directory synchronizing software, there is no merging at all - just simple file overwrite, despite many people believing that the data is somehow combined and preserved.
|
|
|
|
The Taskserver is a solution.
|
|
It is an online/cloud storage and sync service for taskwarrior data.
|
|
It performs conflict-free data merging, and minimizes bandwidth use.
|
|
|
|
The Taskserver also provides multi-client access, so that a task added using a web client could be immediately viewed using a mobile client, or modified using taskwarrior.
|
|
Choice of clients is important - people have widely varying behaviors and tastes.
|
|
|
|
The Taskserver also provides multi-user access, which introduces new capabilities, such as list sharing and delegation.
|
|
These will require later modification to this protocol.
|
|
|
|
The Taskserver protocol will be implemented by the taskd project and first used in taskwarrior 2.3.0.
|
|
Other clients will follow.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
## Link Level
|
|
|
|
The Taskserver protocol assumes a reliable data stream such as provided by TCP.
|
|
When TCP is used, a Taskserver listens on a single predetermined port *for the given client* only.
|
|
This means the server may be using multiple ports to serve distinct sets of clients.
|
|
|
|
This server is only an interface between programs and the task data.
|
|
It does not perform any user interaction or presentation-level functions.
|
|
|
|
|
|
## Transactions
|
|
|
|
Each transaction is a single incoming message, with a single response message.
|
|
All communication therefore consists of a single 'send', followed by a single 'receive', then termination.
|
|
There are no sessions, and no continuously open connections.
|
|
The message format is described in the [Taskserver Message Format](/docs/design/request) document.
|
|
|
|
|
|
## Responsibilities of the Server
|
|
|
|
The server will maintain a set of transactions, in the original sequence, punctuated by sync keys which are UUIDs.
|
|
Each sync key represents a non- trivial sync operation by a client.
|
|
Each transaction is a [JSON-formatted task](/docs/design/task), followed by a newline (\\n) character.
|
|
The result is a single file that contains interleaved lines of two types: tasks and sync keys.
|
|
|
|
This design allows the server to maintain a set of deltas such that multiple clients may request a minimal set of changes since their last sync.
|
|
|
|
|
|
## Responsibilities of the Client
|
|
|
|
This describes how Taskwarrior implements sync.
|
|
|
|
All modifications to tasks (add, modify, done, delete \...) are recorded in the form of a fully-composed [JSON-formatted task](/docs/design/task).
|
|
The formatted task is added to a local backlog.data file.
|
|
If a task is modified a second time, it is added again to the backlog.data file - the lines are not combined.
|
|
Each task SHALL have a 'modified' date attribute that will help resolve conflicts.
|
|
|
|
On sync:
|
|
|
|
* Send a 'sync' type message with the entire contents of the backlog.data, unmodified, as the message payload.
|
|
|
|
* Receive one of the following response codes:
|
|
|
|
* 201: This means 'no change', and there is no further action to be taken.
|
|
|
|
* 200: This means 'success', and the message payload contains a set of tasks and a sync key:
|
|
|
|
* The formatted tasks are to be stored as-is.
|
|
These tasks will either be appended to the client data or will overwrite existing client data, based on the UUID of the task.
|
|
No merge logic is necessary.
|
|
|
|
* The sync key will be written to the backlog.data file, overwriting the previous contents, such that it will now contain only one line.
|
|
|
|
* 301: Redirect to : found in the 'info' response header, will force the client to resubmit the request to the new server.
|
|
|
|
* 3xx, 4xx, 5xx: The 'status' field contains an error message.
|
|
|
|
* If the response contained any error or warning, the error should be shown to the user.
|
|
This provides an opportunity for the server to announce downtime, or relocation.
|
|
|
|
If no sync key is sent, the server cannot provide an incremental delta, and so will send all task data, which should be stored as above.
|
|
This should be the case for a client making its first sync call.
|
|
|
|
If an unrecognized attribute is present in the task data, the client MUST preserve the attribute unmodified, and assume it is of type 'string'.
|
|
This permits individual clients to augment the task data without other clients stripping it meaningful data.
|
|
This is how UDAs (user defined attributes) are handled.
|
|
|
|
|
|
## Extensions
|
|
|
|
This protocol was designed so that extensions to the protocol will take the form of additional message types and status codes.
|
|
|
|
|
|
## Summary of Response Codes
|
|
|
|
Status responses indicate the server's response to the last command received from the client.
|
|
The codes consist of a 3 digit numeric code.
|
|
|
|
The first digit of the response broadly indicates the success, failure, or progress of the previous command (based generally on [RFC640](https://tools.ietf.org/html/rfc640) [RFC821](https://tools.ietf.org/html/rfc821)):
|
|
|
|
| 1yz | Positive Preliminary reply |
|
|
| 2yz | Positive Completion reply |
|
|
| 3yz | Positive Intermediate reply |
|
|
| 4yz | Transient Negative Completion reply |
|
|
| 5yz | Permanent Negative Completion reply |
|
|
|
|
The next digit in the code indicates the response category:
|
|
|
|
| x0z | Syntax |
|
|
| x1z | Information (e.g., help) |
|
|
| x2z | Connections |
|
|
| x3z | Authentication |
|
|
| x4z | Unspecified as yet |
|
|
| x5z | Taskd System (\...) |
|
|
| x8z | Nonstandard (private implementation) extensions |
|
|
|
|
A summary of all status response are:
|
|
|
|
| 200 | Success |
|
|
| 201 | No change |
|
|
| 300 | Deprecated message type. This message will not be supported in future Taskserver releases. |
|
|
| 301 | Redirect. Further requests should be made to the specified server/port. |
|
|
| 302 | Retry. The client is requested to wait and retry the same request. The wait time is not specified, and further retry responses are possible. |
|
|
| 400 | Malformed data |
|
|
| 401 | Unsupported encoding |
|
|
| 420 | Server temporarily unavailable |
|
|
| 421 | Server shutting down at operator request |
|
|
| 430 | Access denied |
|
|
| 431 | Account suspended |
|
|
| 432 | Account terminated |
|
|
| 500 | Syntax error in request |
|
|
| 501 | Syntax error, illegal parameters |
|
|
| 502 | Not implemented |
|
|
| 503 | Command parameter not implemented |
|
|
| 504 | Request too big |
|
|
|
|
## Security Considerations
|
|
|
|
All communication with the Taskserver uses SSL 3.0 or TLS 1.0, 1.1 or 1.2.
|
|
Encryption is mandatory.
|
|
Data is never transmitted in plain text.
|
|
|
|
|
|
## Limitations and Guidelines
|
|
|
|
Some limitations exists to reduce bandwidth and load on the server.
|
|
They are:
|
|
|
|
- A client may only connect to a single server.
|
|
Synchronization among a set of servers is not supported.
|
|
|
|
- A client should attempt to minimize data bandwidth usage by maintaining a local data store, and properly using sync keys.
|
|
|
|
- A client should minimize data transfers by limiting the frequency of sync requests.
|