Göteborg Bit Factory                                                  June 2013

                           Taskserver Message Format
                                   Version 1


Status of this Memo

   This document provides information for the Internet community.  It does not
   specify an Internet standard of any kind.  Distribution of this document is
   not restricted.


Copyright Notice

   Copyright (C) 2010 - 2014, Göteborg Bit Factory


Abstract

   The Taskserver accepts and emits only messages.  These messages look somewhat
   like email [RFC821, RFC2822].


Table of Contents

   1      Introduction
   1.1      Requirements
   2      Messages
   2.1      Message Format
   2.2      Message Requirements
   2.3      Authentication Data
   2.4      Status Data
   2.5      Payload
   3      Message Types
   3.1      Message Type "sync"
   3.2      Message Type "statistics"
   4      References
   5      Acknowledgements
   6      Authors' Addresses
   7      Full Copyright Statement


1   Introduction

   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.


1.1  Requirements

   In this document, we adopt the convention discussed in Section 1.3.2 of
   [RFC1122] 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.


2  Messages

   All messages are UTF8-encoded text.


2.1  Message Format

   This format is based on [RFC2822], 'Internet Message Format'.  Here is an
   example of the format:

      <SIZE>
      name: value\n
      name2: value2\n
      \n
      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.

   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.


2.2  Message Requirements

   Messages SHALL contain particular headers.  Those are:

      type
      protocol
      client

   The 'type' value is what determines the interpretation of the payload.

   The 'protocol' value should be 'v1' [1], 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:

      <product identifier> <version number>

   As an example:

      taskwarrior 2.3.0

   DO NOT spoof any other software using this client value.  If another client
   is spoofed, then patches supporting protocol errors may break working
   software.


2.3  Auth Data

   Every request from the client SHALL contain "auth" information, which
   involves these header entries:

      org: <organization>
      user: <user>
      key: <key>

   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.

   Authentication failure can result in these errors:
       430 Authentication failed
       431 Account suspended


2.4  Status Data

   Every response from the Taskserver SHALL contain status data:

      code: <code>
      status: <status text>

   The code is a numeric status indicator defined in the protocol spec
   [1, RFC640].


2.5  Payload Data

   Payload data is optional, arbitrary and message type dependent.  It is always
   UTF8-encoded text.


3  Message Types

   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.


3.1  Message Type "sync"

   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:

      - type
      - org
      - user
      - key
      - client
      - protocol

   The "sync" message payload has this format:

      <uuid>\n
      <JSON task 1>\n
      <JSON task 2>\n
      ...
      <JSON task N>\n

   Here is an example of a sync message:

      <size>type: sync
      org: <organization>
      user: <user>
      key: <key>
      client: task 2.3.0
      protocol: v1

      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).

   An example response message might be:

      <size>type: response
      client: taskd 1.0.0
      protocol: v1
      code: 200
      status: Ok

      45da7110-1bcc-4318-d33e-12267a774e0f

   The status indicates success, and the payload contains zero remote task
   modifications, followed by a sync key.


3.2  Message Type "statistics"

      type: statistics
      org: <Organization>
      user: <User>
      key: <Key>
      client: taskd 1.0.0
      protocol: v1

   There is no payload.  An example response message might be:

      <size>type: response
      client: taskd 1.0.0
      protocol: v1
      code: 200
      status: Ok
      average request bytes: 0
      average response bytes: 0
      average response time: 0.000000
      errors: 0
      idle: 1.000000
      maximum response time: 0.000000
      total bytes in: 0
      total bytes out: 0
      tps: 0.000000
      transactions: 1
      uptime: 28

   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.


4  References
 
   [1] Beckingham P., Hernandez, F., "Taskserver Protocol", Version 1,
        June 2013.

   [2] Beckingham, P., Hernandez, F., "Taskwarrior Data Interchange Format
        (JSON)", Version 1, June 2013.

   [RFC640] Postel, J., "Revised FTP Reply Codes", RFC 640, June,
        1975.

   [RFC821] Postel, J., "Simple Mail Transfer Protocol", STD 10,
        RFC 821, August 1982.

   [RFC1122] IETF, "Requirements for Internet Hosts - Communication
        Layers", October 1989.

   [RFC2822] Resnick, P., "Internet Message Format", April 2001.


5  Acknowledgements

   Thanks to ... whose comments helped improve this document.


6  Authors' Addresses

   Paul Beckingham
   Email: paul@taskwarrior.org

   Federico Hernandez
   Email: fredde@taskwarrior.org


7  Full Copyright Statement

   Copyright 2010 - 2014, Göteborg Bit Factory.
   All rights reserved.

   This document and translations of it may be copied and furnished to others,
   and derivative works that comment on or otherwise explain it or assist in its
   implementation may be prepared, copied, published and distributed, in whole
   or in part, without restriction of any kind, provided that the above
   copyright notice and this paragraph are included on all such copies and
   derivative works.  However, this document itself may not be modified in any
   way, such as by removing the copyright notice or by omission of certain
   sections.

   The limited permissions granted above are perpetual and will not be revoked
   by the authors or their successors or assigns.

   This document and the information contained herein is provided on an "AS IS"
   basis and the authors disclaim all warranties, express or implied, including
   but not limited to any warranty that the use of the information herein will
   not infringe any rights or any implied warranties of merchantability or
   fitness for a particular purpose.

---

