spritehttpd/spritehttpd/include/httpd-types.h

/**
 * Type definitions used in the http server
 */

#pragma once

#include <stdint.h>
#include <stddef.h>
#include "httpd-config.h"

// opaque conn type struct
struct HttpdConnType;
typedef struct HttpdConnType HttpdConnType;
typedef HttpdConnType* ConnTypePtr;

struct httpd_thread_handle;
typedef struct httpd_thread_handle httpd_thread_handle_t;

struct httpd_init_options;

typedef uint32_t httpd_ipaddr_t;

/**
 * CGI handler state / return value
 */
typedef enum {
  /// Some work was done and the CGI wants to be called again at a later time.
  /// Splitting long-running jobs allows other requests to be handled.
  HTTPD_CGI_MORE = 0,
  /// The CGI handled the request and is now done with it
  HTTPD_CGI_DONE = 1,
  /// This CGI did not handle the request, fall through to following ones
  HTTPD_CGI_NOTFOUND = 2,
  /// This is, in effect, identical to NOTFOUND, it's returned by auth functions when a fall-through is allowed.
  /// The next route in the route list will be attempted.
  HTTPD_CGI_AUTHENTICATED = 3, // TODO rename to PASS?
} httpd_cgi_state;

/**
 * HTTP method (verb) used for the request
 */
typedef enum {
  HTTPD_METHOD_GET = 1,
  HTTPD_METHOD_POST = 2,
  HTTPD_METHOD_OPTIONS = 3,
  HTTPD_METHOD_PUT = 4,
  HTTPD_METHOD_DELETE = 5,
  HTTPD_METHOD_PATCH = 6,
  HTTPD_METHOD_HEAD = 7,
} httpd_method;

/**
 * Transfer mode
 */
typedef enum {
  HTTPD_TRANSFER_CLOSE = 0,
  HTTPD_TRANSFER_CHUNKED = 1,
  HTTPD_TRANSFER_NONE = 2,
} httpd_transfer_opt;


/* init options */

struct httpd_init_options {
  uint16_t port;
};


/* Private types - exposed to allow static alloc */

struct HttpdQueuedHeader;
typedef struct HttpdQueuedHeader {
  /// Pointer to the next queued header
  struct HttpdQueuedHeader *next;
  /// Text of the header, including CRLF
  char headerLine[];
} HttpdQueuedHeader;

typedef struct HttpdSendBacklogItem HttpdSendBacklogItem;
struct HttpdSendBacklogItem {
  size_t len;
  HttpdSendBacklogItem *next;
  uint8_t data[];
};

//Private data for http connection
typedef struct HttpdPriv HttpdPriv;
struct HttpdPriv {
  char head[HTTPD_MAX_HEAD_LEN];
  char corsToken[HTTPD_MAX_CORS_TOKEN_LEN];
  size_t headPos;
  uint8_t *sendBuff;
  size_t sendBuffLen;
  char *chunkHdr;
  HttpdSendBacklogItem *sendBacklog;
  HttpdQueuedHeader *headersToSend; // Linked list of headers to send with the response. Will be freed with the request.
  size_t sendBacklogSize;
  uint8_t flags;
};

/// Callback type that releases the user data attached to the connection.
/// The format is compatible with regular "free()" or
typedef void (* httpdUserDataCleanupCb)(void *userData);


//A struct describing the POST data sent inside the http connection. This is used by the CGI functions
typedef struct HttpdPostData HttpdPostData;
struct HttpdPostData {
  // FIXME len can be negative due to a stupid hack at `src/httpd.c:923`
  int len;				// POST Content-Length
  size_t buffSize;			// The maximum length of the post buffer
  size_t buffLen;			// The amount of bytes in the current post buffer
  size_t received;			// The total amount of bytes received so far
  char *buff;				// Actual POST data buffer
  char *multipartBoundary; //Text of the multipart boundary, if any
};

typedef struct HttpdConnData HttpdConnData;
typedef httpd_cgi_state (* cgiSendCallback)(HttpdConnData *connData);
typedef httpd_cgi_state (* cgiRecvHandler)(HttpdConnData *connData, uint8_t *data, size_t len);

//A struct describing a http connection. This gets passed to cgi functions.
struct HttpdConnData {
  ConnTypePtr conn;		// The TCP connection. Exact type depends on the platform.
  HttpdPriv priv;		// Internal httpd state for the connection

  httpd_method requestType; // One of the HTTPD_METHOD_* values
  char *hostName;			// Host name field of request
  char *url;				// The URL requested, without hostname or GET arguments
  char *getArgs;			// The GET arguments for this request, if any.
  HttpdPostData post;	    // POST data structure

  cgiSendCallback cgi;	    // CGI function pointer
  cgiRecvHandler recvHdl;	// Handler for data received after headers, if any
  const void *cgiArg;		// First CGI argument, can be NULL if not needed
  const void *cgiArg2;	    // Second CGI argument for CGIs that need two parameters
  void *cgiData;            // Opaque data pointer for the CGI function

  /// Opaque data pointer for user data that carries over between CGI calls for the same connection.
  void *userData;
  /// If userData is not NULL when a connection is finalized, this function (if set) is called to handle the cleanup.
  /// This mechanism is useful when the user data is allocated by an auth CGI and the request can end in any number
  /// of other routes, perhaps even with a static file - then the cleanup code doesn't need to be repeated everywhere.
  httpdUserDataCleanupCb userDataCleanupCb;

  // this should be at the end because of padding
  uint16_t remote_port;		// Remote TCP port
  httpd_ipaddr_t remote_ip;		// IP address of client
  uint8_t slot;				// Slot ID - index in s_connData
};