| /*****************************************************************************\ | |
| * http_request.h - HTTP on request handler | |
| ***************************************************************************** | |
| * Copyright (C) SchedMD LLC. | |
| * | |
| * This file is part of Slurm, a resource management program. | |
| * For details, see <https://slurm.schedmd.com/>. | |
| * Please also read the included file: DISCLAIMER. | |
| * | |
| * Slurm is free software; you can redistribute it and/or modify it under | |
| * the terms of the GNU General Public License as published by the Free | |
| * Software Foundation; either version 2 of the License, or (at your option) | |
| * any later version. | |
| * | |
| * In addition, as a special exception, the copyright holders give permission | |
| * to link the code of portions of this program with the OpenSSL library under | |
| * certain conditions as described in each individual source file, and | |
| * distribute linked combinations including the two. You must obey the GNU | |
| * General Public License in all respects for all of the code used other than | |
| * OpenSSL. If you modify file(s) with this exception, you may extend this | |
| * exception to your version of the file(s), but you are not obligated to do | |
| * so. If you do not wish to do so, delete this exception statement from your | |
| * version. If you delete this exception statement from all source files in | |
| * the program, then also delete it here. | |
| * | |
| * Slurm 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 General Public License for more | |
| * details. | |
| * | |
| * You should have received a copy of the GNU General Public License along | |
| * with Slurm; if not, write to the Free Software Foundation, Inc., | |
| * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. | |
| \*****************************************************************************/ | |
| #ifndef SLURM_HTTP_REQUEST_H | |
| #define SLURM_HTTP_REQUEST_H | |
| #include "src/common/http.h" | |
| #include "src/common/http_con.h" | |
| #include "src/common/macros.h" | |
| #include "src/interfaces/data_parser.h" | |
| /* Opaque event state passed between _on_request() and http_request_reply() */ | |
| typedef struct http_request_event_s http_request_event_t; | |
| /* | |
| * Called after successful HTTP authentication and MIME negotiation. | |
| * IN event - opaque request event state (pass to http_request_reply()) | |
| * IN hcon - pointer to HTTP connection | |
| * IN name - connection name for logging | |
| * IN uid - authenticated user id | |
| * IN method - HTTP request method | |
| * IN request - pointer to parsed HTTP request | |
| * IN arg - arbitrary pointer handed to http_request_bind() | |
| * RET SLURM_SUCCESS or error | |
| */ | |
| typedef int (*http_request_on_request_t)(http_request_event_t *event, | |
| http_con_t *hcon, const char *name, | |
| const uid_t uid, | |
| http_request_method_t method, | |
| const http_con_request_t *request, | |
| void *arg); | |
| /* | |
| * Called when HTTP request processing encounters an error (e.g. | |
| * authentication failure or unsupported MIME type). | |
| * IN event - opaque request event state | |
| * IN hcon - pointer to HTTP connection | |
| * IN name - connection name for logging | |
| * IN request - pointer to parsed HTTP request | |
| * IN err - error code describing the failure | |
| * RET SLURM_SUCCESS or error | |
| */ | |
| typedef int (*http_request_on_error_t)(http_request_event_t *event, | |
| http_con_t *hcon, const char *name, | |
| const http_con_request_t *request, | |
| int err); | |
| /* | |
| * Bind an HTTP path to request and error callbacks. Handles authentication | |
| * and MIME negotiation before invoking on_request. When reply_type is not | |
| * DATA_PARSER_TYPE_INVALID, the path is registered once per parser version | |
| * that supports the given type (substituting OPENAPI_DATA_PARSER_PARAM in | |
| * path with the parser version string). | |
| * NOTE: Use http_request_bind() macro instead of calling directly. | |
| * IN parsers - NULL-terminated array of data parsers | |
| * IN method - HTTP method to bind | |
| * IN path - URL path to bind (may contain OPENAPI_DATA_PARSER_PARAM) | |
| * IN on_request - callback for authenticated requests | |
| * IN on_request_func - string of function name | |
| * IN on_error - callback for request processing errors | |
| * IN on_error_func - string of function name | |
| * IN reply_type - data parser type for serializing replies, or | |
| * DATA_PARSER_TYPE_INVALID for untyped replies | |
| * IN arg - arbitrary pointer passed through to on_request callback | |
| */ | |
| extern void http_request_bind_funcname(data_parser_t **parsers, | |
| http_request_method_t method, | |
| const char *path, | |
| http_request_on_request_t on_request, | |
| const char *on_request_func, | |
| http_request_on_error_t on_error, | |
| const char *on_error_func, | |
| data_parser_type_t reply_type, | |
| void *arg); | |
| /* | |
| * Bind an HTTP path to request and error callbacks. Handles authentication | |
| * and MIME negotiation before invoking on_request. When reply_type is not | |
| * DATA_PARSER_TYPE_INVALID, the path is registered once per parser version | |
| * that supports the given type (substituting OPENAPI_DATA_PARSER_PARAM in | |
| * path with the parser version string). | |
| * IN parsers - NULL-terminated array of data parsers | |
| * IN method - HTTP method to bind | |
| * IN path - URL path to bind (may contain OPENAPI_DATA_PARSER_PARAM) | |
| * IN on_request - callback for authenticated requests | |
| * IN on_error - callback for request processing errors | |
| * IN reply_type - data parser type for serializing replies, or | |
| * DATA_PARSER_TYPE_INVALID for untyped replies | |
| * IN arg - arbitrary pointer passed through to on_request callback | |
| */ | |
| #define http_request_bind(parsers, method, path, on_request, on_error, \ | |
| reply_type, arg) \ | |
| http_request_bind_funcname((parsers), (method), (path), (on_request), \ | |
| XSTRINGIFY(on_request), (on_error), \ | |
| XSTRINGIFY(on_error), \ | |
| (reply_type), (arg)) | |
| /* | |
| * Send an HTTP response for a bound request. When a parser is associated with | |
| * the binding and reply is non-NULL, the reply is serialized using the bound | |
| * data parser type and the negotiated write MIME type. When no parser is | |
| * associated, the raw reply bytes are sent as text. When reply is NULL, an | |
| * empty response with the appropriate status code is sent. | |
| * IN event - opaque request event state from on_request callback | |
| * IN rc - result code (mapped to HTTP status via http_status_from_error()) | |
| * IN headers - optional list of additional HTTP headers (or NULL) | |
| * IN close_header - if true, include Connection: close header | |
| * IN reply - pointer to response data to serialize (or NULL) | |
| * IN reply_bytes - size of reply data in bytes | |
| * RET SLURM_SUCCESS or error | |
| */ | |
| extern int http_request_reply(http_request_event_t *event, int rc, | |
| list_t *headers, bool close_header, void *reply, | |
| size_t reply_bytes); | |
| #endif |