/*

  Copyright 2010 Nathan Phillip Brink

  This file is a part of DistRen.

  DistRen is free software: you can redistribute it and/or modify

  it under the terms of the GNU Affero General Public License as published by

  the Free Software Foundation, either version 3 of the License, or

  (at your option) any later version.

  DistRen is distributed in the hope that it will be useful,

  but WITHOUT ANY WARRANTY; without even the implied warranty of

  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

  GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License

  along with DistRen.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef DISTREN_PROTOCOL_H

#define DISTREN_PROTOCOL_H

#include <openssl/evp.h>

#include <stddef.h>

#include <stdint.h>

/**

 * Server types:

 *

 * It is assumed that any client has at least the functionality of a

 * normal client (i.e., accepts all of the REQUIRED requests). These

 * bitmask values add to the types of requests one may make to a

 * server. After first connecting to a server or receiving a

 * connection, a client shall send a DISTREN_REQUEST_VERSION packet

 * describing its version.

 */

#define DISTREN_SERVERTYPE_SUBMIT (0x1)

#define DISTREN_SERVERTYPE_DISTRIBUTE (0x2)

#define DISTREN_SERVERTYPE_RENDER (0x4)

#define DISTREN_SERVERTYPE_CLIENT (0x8)

/**

 * This file defines the constants and structs that distren clients

 * and server use to converse.

 */

/**

 * List of request types and metadata.

 */

enum distren_request_type

  {

    /**

     * identifies the version of software being used by the sender and

     * tells if it is a client or server. Sends PACKAGE_STRING as well

     * as informing the other server what type of server this is.

     *

     *

     * REQUIRED: ALL

    */

    DISTREN_REQUEST_VERSION = 1,

    /**

     * Test if the end has a live server.

     *

     * Only authenticated clients may use this request. Thus, if a

     * client wants to confirm that a DISTREN_REQUEST_PASS request was

     * successful, that client may send a DISTREN_REQUEST_PING

     * immediately after the DISTREN_REQUEST_PASS and then wait for

     * the PONG.

     *

     * DATA: up to 32 bytes of a PING cookie

     *

     * REQUIRED: ALL

     */

    DISTREN_REQUEST_PING = 2,

    /**

     * Response to DISTREN_REQUEST_PING.

     *

     * Unauthenticated clients may be penalized for responding to PING

     * requests. This is because a newly connecting client should

     * queue a DISTREN_REQUEST_VERSION and DISTREN_REQUEST_PASS

     * back-to-back before checking for and processing data from the

     * remote server.

     *

     * DATA: up to 32 bytes copied from a received PING cookie

     *

     * REQUIRED: ALL

     */

    DISTREN_REQUEST_PONG = 3,

    /**

     * The data is the a reason describing why the one end is

     * disconnecting. The other end should respectfully close()

     * the socket or the sender will timeout shortly.

     *

     * DATA: A string describing the reason for the connection's

     * termination.

     *

     * REQUIRED: ALL

     */

    DISTREN_REQUEST_DISCONNECT = 4,

    /**

     * Allow a client to identify itself using simple password

     * authentication.

     *

     * As there is no distren request which affirms a

     * DISTREN_REQUEST_PASS went through, clients may send a

     * DISTREN_REQUEST_PING and wait for the DISTREN_REQUETS_PONG they

     * want to block until they're authenticated.

     *

     * DATA: struct distren_request_pass

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT (for now, since

     * server2server links are only protected using password

     * authentication, all server types have to support this except

     * for the client.)

     */

    DISTREN_REQUEST_PASS = 5,

    /**

     * DATA: struct distren_request_submit

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT

     */

    DISTREN_REQUEST_SUBMIT = 6,

    /**

     * Inform the other party about a job.

     *

     * DATA: struct distren_request_jobinfo

     *

     * REQUIRED: ALL

     */

    DISTREN_REQUEST_JOBINFO = 7,

    /**

     * Request a DISTREN_REQUEST_JOBINFO

     *

     * DATA: struct distren_request_jobinfo_get

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT, DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_JOBINFO_GET = 8,

    /**

     * Command the other party to render a frame

     *

     * DATA: struct distren_request_frame_render

     *

     * REQUIRED: DISTREN_SERVERTYPE_RENDER

     */

    DISTREN_REQUEST_FRAME_RENDER = 9,

    /**

     * Inform the receiver of the sender's state, such as frames being

     * rendered or jobs that need to be completed.

     *

     * DATA: struct distren_request_status

     *

     * REQUIRED: DISTREN_SERVERTYPE_RENDER, DISTREN_SERVERTYPE_DISTRIBUTE, DISTREN_SERVERTYPE_CLIENT

     */

    DISTREN_REQUEST_STATUS = 10,

    /**

     * Request that the receiver send a DISTREN_REQUEST_FRAME_STATUS

     * packet. No data because the sending party might not beforehand

     * know what frames/jobs the receiving server is managing.

     *

     * DATA: (none)

     *

     * REQUIRED: DISTREN_SERVERTYPE_RENDER

     */

    DISTREN_REQUEST_STATUS_GET = 11,

    /**

     * Declare that a client is preparing to post a file using a

     * particular post-id and with a user-friendly filename.

     *

     * Yes, this is evil. Yes, this tries to replicate

     * well-established protocols like FTP and HTTP (which is

     * sometimes itself mistreated as FTP). Yes, this will be

     * buggy. Why is it needed? For my personal coding experience and

     * because I don't know off-hand of any libraries that allow a

     * file upload to be interleaved over an existing connection with

     * its own protocol. Over TCP? We aren't doing real-time streaming

     * or anything :-p.

     *

     * Possible future expansions: ``transparent'' zlib compression.

     *

     * DATA: struct distren_request_file_post_start

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT, DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_FILE_POST_START = 12,

    /**

     * Allow a client to upload a job tarball over a remoteio line.  A

     * client that wants to do this must take care not to overbuffer

     * his sendqueue so as to be able to respond to PING packets in

     * time. A server receiving such a message will want to write the

     * file as directly to disk as possible to avoid bogging the

     * server down in swap. This packet may only be sent if

     * DISTREN_REQUEST_FILE_POST_START has previously been sent.

     *

     * It is potential that if a server is DISTREN_SERVERTYPE_SUBMIT

     * but not also DISTREN_SERVERTYPE_DISTRIBUTE, that this request

     * would be relayed by the DISTREN_SERVERTYPE_SUBMIT server to a

     * DISTREN_SERVERTYPE_DISTRIBUTE server so that other clients can

     * obtain the file from the distribution server. In this case, the

     * file's URL is already known.

     *

     * Of course, having this sort of functionality at all is where

     * the nasty security issues start coming into play :-D.

     *

     * DATA: struct distren_request_file_post followed by a maximum of 131072 bytes (128kB).

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT, DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_FILE_POST = 13,

    /**

     * Marks a post-id's file as having completely uploaded. Provides

     * verification information so that the file's integrity may be

     * verified.

     *

     * DATA: struct distren_request_file_post_finish

     *

     * REQUIRED: DISTREN_SERVERTYPE_SUBMIT, DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_FILE_POST_FINISH = 14,

    /**

     * Request information about obtaining a file (such as a

     * cURL-compatible URL) based on a distren file URL.

     *

     * DATA: struct distren_request_file_find

     *

     * REQUIRED: DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_FILE_FIND = 15,

    /**

     * Provide information about obtaining a file (such as a URL).

     *

     * DATA: struct distren_request_file

     *

     * REQUIRED: DISTREN_SERVERTYPE_DISTRIBUTE

     */

    DISTREN_REQUEST_FILE = 16,