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
15 ** Table of Content **
16 ----------------------
26 |-Monkey exported functions
31 This draft specified the Plugin API for Monkey HTTP Daemon v0.11.0.
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.
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.
47 A plugin must contains at least the following hooks functions:
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 ------------------+---------------------------------------------------------------
61 void _mkp_init(struct plugin_api **api, char *confdir)
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 ---------------------+------------------------------------------------------------
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)
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.
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 ---------+-----------------------+-------------------+-----------------------------------
112 void _mkp_core_prctx()
113 void _mkp_core_thctx()
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 ---------+----------------------+------------------+---------------------------------------------
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)
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
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 ---------+-----------------------+-----------------------------+---------------------------------
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)
180 char *_mkp_network_ip_addr(int sockfd)
181 int _mkp_network_ip_maxlen()
185 A plugin *must* define it self with the following information:
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;
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
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.
209 Considering 'api' as the API structure, we have the following available
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
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
255 -------------------------------------------------------+---------------------------------------------------------
256 int iov_set_entry(struct mk_iov *mk_io, | Add an entry to the iov structure in a specific position
261 -------------------------------------------------------+---------------------------------------------------------
262 ssize_t iov_send(int fd, | Send iov structure to a socket or pipe
263 struct mk_iov *mk_io, |
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
289 -------------------------------------------------------+---------------------------------------------------------
290 struct sched_connection | Get connection scheduler details
291 *sched_get_connection(struct sched_list_node *sched, |
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 -------------------------------------------------------+---------------------------------------------------------