plugins/API.txt

   1 ** Revision 0.8 **
   2
   3 Changelog:
   4 ----------
   5 0.8: Add plugins API definition
   6 0.7: Add functions definition
   7 0.6: Add a list of Monkey functions exported to each plugin
   8 0.5: Add _mkp_init() and _mkp_exit() hook functions
   9 0.4: Add hook function names
  10 0.3: Add 'TOC' and 'About' sections
  11 0.2: Add Plugin code definition example
  12 0.1: Initial draft
  13
  14
  15 ** Table of Content **
  16 ----------------------
  17 |-About
  18 |-Monkey API
  19   |-Monkey Plugins
  20     |-Mandatory calls
  21     |-Plugin type
  22       |-Core
  23       |-Stage
  24       |-Networking
  25     |-Plugin definition
  26   |-Monkey exported functions
  27
  28
  29 ** About **
  30 -----------
  31 This draft specified the Plugin API for Monkey HTTP Daemon v0.11.0.
  32
  33
  34 ** Monkey API **
  35 ----------------
  36 The Monkey API allows to extend the Monkey features and behavior through plugins,
  37 which are shared libraries loaded on startup. It also provides a set of specific
  38 functions to make easier the developer work.
  39
  40 Monkey Plugins
  41 --------------
  42 A plugin is composed by a set of mandatory plus optional function calls that act
  43 like hooks that are called from Monkey Core.
  44
  45 Mandatory hook calls
  46 --------------------
  47 A plugin must contains at least the following hooks functions:
  48
  49 ------------------+---------------------------------------------------------------
  50  Hook function    | Description
  51 ------------------+---------------------------------------------------------------
  52   _mkp_init()     | Function called when registering the plugin, it also allows
  53                   | to set basic configuration.
  54 ------------------+---------------------------------------------------------------
  55   _mkp_exit()     | Function called before to unload the plugin, the plugin
  56                   | must free the used memory resources
  57 ------------------+---------------------------------------------------------------
  58
  59 Definitions
  60 -----------
  61 void _mkp_init(struct plugin_api **api, char *confdir)
  62 void _mkp_exit()
  63
  64
  65 Optional hook calls
  66 -------------------
  67 These hook functions are invoked when a epoll event has been set through
  68 event_add() by the plugin
  69 ---------------------+------------------------------------------------------------
  70  Hook function       | Description
  71 ---------------------+------------------------------------------------------------
  72   _mkp_event_read    | FD set is ready to read
  73 ---------------------+------------------------------------------------------------
  74   _mkp_event_write   | FD set is ready to write
  75 ---------------------+------------------------------------------------------------
  76   _mkp_event_close   | FD has been closed
  77 ---------------------+------------------------------------------------------------
  78   _mkp_event_error   | An error has been detected in the file descriptor
  79 ---------------------+------------------------------------------------------------
  80   _mkp_event_timeout | Timeout detected in the file descriptor
  81 ---------------------+------------------------------------------------------------
  82
  83 Definitions
  84 -----------
  85 int _mkp_event_read(struct client_request *cr, struct request *sr)
  86 int _mkp_event_write(struct client_request *cr, struct request *sr)
  87 int _mkp_event_close(struct client_request *cr, struct request *sr)
  88 int _mkp_event_error(struct client_request *cr, struct request *sr)
  89 int _mkp_event_timeout(struct client_request *cr, struct request *sr)
  90
  91
  92 Plugin and Function Hooks
  93 -------------------------
  94 The following sections defines the type of plugin and each hook function associated. A
  95 plugin can be registered to use multiple hooks just adding the right identifiers.
  96
  97 -------+
  98  Core  |
  99 -------+---------------------------------------------------------------------------------
 100  The Core plugins allow other plugins to define some data in the process context or
 101  thread context depending of it needs.
 102 ---------+-----------------------+-------------------+-----------------------------------
 103  Context |  Identified by        | Hook function     | Description
 104 ---------+-----------------------+-------------------+-----------------------------------
 105  Process | MK_PLUGIN_CORE_PRCTX  | _mkp_core_prctx() | Process context, no server loop
 106 ---------+-----------------------+-------------------+-----------------------------------
 107  Thread  | MK_PLUGIN_CORE_THCTX  | _mkp_core_thctx() | Thread context, no server loop
 108 ---------+-----------------------+-------------------+-----------------------------------
 109
 110 Definitions
 111 -----------
 112 void _mkp_core_prctx()
 113 void _mkp_core_thctx()
 114
 115 -------+
 116  Stage |
 117 -------+-----------------------------------------------------------------------------------------
 118  Every single http request is placed in a cycle of stages. The request pass around five stages
 119  and each one provides a hook function which is invoked by Monkey.
 120 ---------+----------------------+------------------+---------------------------------------------
 121  Stage # |    Identified by     | Hook function    | Description
 122 ---------+----------------------+------------------+---------------------------------------------
 123    10    |  MK_PLUGIN_STAGE_10  | _mkp_stage_10()  | Connection just accept()ed, not assigned
 124 1---------+----------------------+------------------+---------------------------------------------
 125    20    |  MK_PLUGIN_STAGE_20  | _mkp_stage_20()  | HTTP Request stream just received
 126 ---------+----------------------+------------------+---------------------------------------------
 127    30    |  MK_PLUGIN_STAGE_30  | _mkp_stage_30()  | Object handler, what to do with the request?
 128 ---------+----------------------+------------------+---------------------------------------------
 129    40    |  MK_PLUGIN_STAGE_40  | _mkp_stage_40()  | Request ended, content served
 130 ---------+----------------------+------------------+---------------------------------------------
 131    50    |  MK_PLUGIN_STAGE_50  | _mkp_stage_50()  | Remote connection has been closed
 132 ---------+----------------------+------------------+---------------------------------------------
 133
 134 Definitions
 135 -----------
 136 int _mkp_stage_10(int sockfd)
 137 int _mkp_stage_20(struct client_request *cr, struct request *sr)
 138 int _mkp_stage_30(struct client_request *cr, struct request *sr)
 139 int _mkp_stage_40(struct client_request *cr, struct request *sr)
 140 int _mkp_stage_50(int sockfd)
 141
 142 ------------+
 143  Networking |
 144 ------------+------------------------------------------------------------------------------------
 145  Networking plugins act like hooks for specific calls from the core, so it basically provides a
 146  mechanism to replace the I/O and IP related functions. Just one running plugin can exists for
 147  each type.
 148 ---------+-----------------------+-----------------------------+---------------------------------
 149   Type   |    Identified by      | Hook function               | Description
 150 ---------+-----------------------+-----------------------------+---------------------------------
 151    io    | MK_PLUGIN_NETWORK_IO  | _mkp_network_io_accept()    | Accept conx
 152          |                       +-----------------------------+---------------------------------
 153          |                       | _mkp_network_io_read()      | Read socket
 154          |                       +-----------------------------+---------------------------------
 155          |                       | _mkp_network_io_write()     | Write to socket
 156          |                       +-----------------------------+---------------------------------
 157          |                       | _mkp_network_io_writev()    | Write iov to socket
 158          |                       +-----------------------------+---------------------------------
 159          |                       | _mkp_network_io_close()     | Close socket
 160          |                       +-----------------------------+---------------------------------
 161          |                       | _mkp_network_io_connect()   | Connect to
 162          |                       +-----------------------------+---------------------------------
 163          |                       | _mkp_network_io_send_file() | Send file
 164 ---------+-----------------------+-----------------------------+---------------------------------
 165    ip    | MK_PLUGIN_NETWORK_IP  | _mkp_network_ip_addr()      | Get IP address from socket
 166          |                       +---------------------------------------------------------------
 167          |                       | _mkp_network_ip_maxlen()    | Get Max IP address length
 168 ---------+-----------------------+-----------------------------+---------------------------------
 169
 170 Definitions
 171 -----------
 172 int _mkp_network_io_accept(int server_fd, struct sockaddr_in sockaddr)
 173 int _mkp_network_io_read(int sockfd, void *buf, int count)
 174 int _mkp_network_io_write(int sockfd, const void *buf, size_t count)
 175 int _mkp_network_io_writev(int sockfd, struct mk_iov *mk_io)
 176 int _mkp_network_io_close(int sockfd)
 177 int _mkp_network_io_connect(const char *host, int port)
 178 int _mkp_network_io_send_file(int sockfd, int filefd, off_t *file_offset, size_t file_count)
 179
 180 char *_mkp_network_ip_addr(int sockfd)
 181 int _mkp_network_ip_maxlen()
 182
 183 Plugin definition
 184 -----------------
 185 A plugin *must* define it self with the following information:
 186
 187   #include "plugin.h"
 188
 189   mkp_data_t _shortname = "shortname";
 190   mkp_data_t _name      = "My Super Plugin";
 191   mkp_data_t _version   = "0.2";
 192   mkp_type_t _types     = MK_PLUGIN_CORE_PRCTX | MK_PLUGIN_NETWORK_IO |
 193                           MK_PLUGIN_STAGE_10 | MK_PLUGIN_STAGE_40;
 194
 195 Field description:
 196
 197  _shortname : A simple word defining the Plugin
 198  _name      : Full plugin name
 199  _version   : Plugin version
 200  _types     : Type of plugin and events associated, it can be a mix of
 201               types.
 202
 203
 204 Monkey exported functions
 205 -------------------------
 206 When Monkey load a plugin and calls the _mkp_init() function, it passed a
 207 structure which contains mapped Monkey functions for different purposes.
 208
 209 Considering 'api' as the API structure, we have the following available
 210 function calls:
 211
 212 -------------------------------------------------------+---------------------------------------------------------
 213  Function                                              | Description
 214 -------------------------------------------------------+---------------------------------------------------------
 215   void *mem_alloc(size_t size)                         | Alloc a memory space
 216 -------------------------------------------------------+---------------------------------------------------------
 217   void *mem_alloc_z(size_t size)                       | Alloc a memory space and set it to zero
 218 -------------------------------------------------------+---------------------------------------------------------
 219   void mem_free(void *ptr)                             | Free a memory space
 220 -------------------------------------------------------+---------------------------------------------------------
 221   char *str_build(char **buffer, unsigned long *len,   | Builds a memory buffer formatting the string parameters
 222                   const char *format, ...)             |
 223 -------------------------------------------------------+---------------------------------------------------------
 224   char *str_dup(const char *s)                         | Duplicate a string buffer
 225 -------------------------------------------------------+---------------------------------------------------------
 226   int str_search(const char *haystack,                 | Return the position of a pattern inside the string
 227                  const char *needle)                   |
 228 -------------------------------------------------------+---------------------------------------------------------
 229   int str_search_n(const char *haystack,               | Search a pattern inside a string with limit in N
 230                    const char *needle)                 |
 231 -------------------------------------------------------+---------------------------------------------------------
 232   char *str_copy_substr(const char *s, int pos_init,   | Copy a substring to a new memory buffer
 233                         int pos_end)                   |
 234 -------------------------------------------------------+---------------------------------------------------------
 235   struct mk_string_line *str_split_line(const char *s) | Split a line using as separator the space character
 236 -------------------------------------------------------+---------------------------------------------------------
 237   char *file_to_buffer(const char *path)               | Reads an entire file into a string buffer
 238 -------------------------------------------------------+---------------------------------------------------------
 239   struct file_info file_get_info(const char *path)     | Get file information
 240 -------------------------------------------------------+---------------------------------------------------------
 241   int header_send(int sockfd,                          | Send header information to the client
 242                   struct client_request *cr,           |
 243                   struct request *sr,                  |
 244                   struct log_info *s_log)              |
 245 -------------------------------------------------------+---------------------------------------------------------
 246   struct mk_iov *iov_create(int len, int offset)       | Alloc an iov structure
 247 --------------------------------+----------------------+----------------------------------
 248   void iov_free(struct mk_iov *mk_io)                  | Free iov structure
 249 -------------------------------------------------------+---------------------------------------------------------
 250   int iov_add_entry(struct mk_iov *mk_io,              | Add an entry to the iov structure
 251                     char *buf,                         |
 252                     int len,                           |
 253                     mk_pointer sep,                    |
 254                     int free)                          |
 255 -------------------------------------------------------+---------------------------------------------------------
 256   int iov_set_entry(struct mk_iov *mk_io,              | Add an entry to the iov structure in a specific position
 257                     char *buf,                         |
 258                     int len,                           |
 259                     int free,                          |
 260                     int idx)                           |
 261 -------------------------------------------------------+---------------------------------------------------------
 262   ssize_t iov_send(int fd,                             | Send iov structure to a socket or pipe
 263                    struct mk_iov *mk_io,               |
 264                    int to)                             |
 265 -------------------------------------------------------+---------------------------------------------------------
 266   void iov_print(struct mk_iov *mk_io)                 | Print iov structure content
 267 -------------------------------------------------------+---------------------------------------------------------
 268   void pointer_set(mk_pointer *p, char *data)          | Set values to a Monkey pointer
 269 -------------------------------------------------------+---------------------------------------------------------
 270   void pointer_print(mk_pointer *p)                    | Print to stdout the data contained in a Monkey pointer
 271 -------------------------------------------------------+---------------------------------------------------------
 272   int socket_cork_flag(int sockfd, int state)          | Enable/Disable socket CORK_FLAG
 273 -------------------------------------------------------+---------------------------------------------------------
 274   int socket_connect(int sockfd, char *host, int port) | Connect to a specific host and port
 275 -------------------------------------------------------+---------------------------------------------------------
 276   int socket_set_tcp_nodelay(int sockfd)               | Set TCP socket on TCP_NODELAY mode
 277 -------------------------------------------------------+---------------------------------------------------------
 278   int socket_set_nonblocking(int sockfd)               | Set socket to non-blocking mode
 279 -------------------------------------------------------+---------------------------------------------------------
 280   int socket_create()                                  | Create a TCP socket
 281 -------------------------------------------------------+---------------------------------------------------------
 282   struct mk_config *config_create(const char *file)    | Create a context for a configuration file
 283 -------------------------------------------------------+---------------------------------------------------------
 284   void config_free(struct mk_config *cnf)              | Free context of a configuration file
 285 -------------------------------------------------------+---------------------------------------------------------
 286   void *config_getval(struct mk_config *cnf,           | Retrieve a specific configuration key value
 287                       const char *key,                 |
 288                       int mode)                        |
 289 -------------------------------------------------------+---------------------------------------------------------
 290   struct sched_connection                              | Get connection scheduler details
 291   *sched_get_connection(struct sched_list_node *sched, |
 292                         int remote_fd)                 |
 293 -------------------------------------------------------+---------------------------------------------------------
 294   int event_add(int sockfd,                            | Register an event handler for a specific file
 295                 struct plugin *handler,                | descriptor, this event is listened in the thread epoll
 296                 struct client_request *cr,             | loop
 297                 struct request *sr)                    |
 298 -------------------------------------------------------+---------------------------------------------------------
 299   int event_socket_change_mode(int sockfd,             | Change the EPOLL event mode for an event added
 300                                int mode)               | with api->event_add()
 301 -------------------------------------------------------+---------------------------------------------------------