/src/h2o/include/h2o/configurator.h

Source
/*
 * Copyright (c) 2014 DeNA Co., Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */
#ifndef h2o__configurator_h
#define h2o__configurator_h

#include "yoml.h"

enum {
    H2O_CONFIGURATOR_FLAG_GLOBAL = 0x1,
    H2O_CONFIGURATOR_FLAG_HOST = 0x2,
    H2O_CONFIGURATOR_FLAG_PATH = 0x4,
    H2O_CONFIGURATOR_FLAG_EXTENSION = 0x8,
    H2O_CONFIGURATOR_FLAG_ALL_LEVELS =
        H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_HOST | H2O_CONFIGURATOR_FLAG_PATH | H2O_CONFIGURATOR_FLAG_EXTENSION,
    H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR = 0x100,
    H2O_CONFIGURATOR_FLAG_EXPECT_SEQUENCE = 0x200,
    H2O_CONFIGURATOR_FLAG_EXPECT_MAPPING = 0x400,
    H2O_CONFIGURATOR_FLAG_DEFERRED = 0x1000,
    H2O_CONFIGURATOR_FLAG_SEMI_DEFERRED =
        0x2000 /* used by listen, file.custom-handler (invoked before hosts,paths,file-dir, etc.) */
};

#define H2O_CONFIGURATOR_NUM_LEVELS 4

typedef struct st_h2o_configurator_context_t {
    /**
     * pointer to globalconf
     */
    h2o_globalconf_t *globalconf;
    /**
     * pointer to hostconf, or NULL if the context is above host level
     */
    h2o_hostconf_t *hostconf;
    /**
     * pointer to pathconf (either at path level or custom handler level), or NULL
     */
    h2o_pathconf_t *pathconf;
    /**
     * pointer to mimemap
     */
    h2o_mimemap_t **mimemap;
    /**
     * pointer to env
     */
    h2o_envconf_t *env;
    /**
     * if is a dry run
     */
    int dry_run;
    /**
     * parent context (or NULL if the context is at global level)
     */
    struct st_h2o_configurator_context_t *parent;
} h2o_configurator_context_t;

typedef int (*h2o_configurator_dispose_cb)(h2o_configurator_t *configurator);
typedef int (*h2o_configurator_enter_cb)(h2o_configurator_t *configurator, h2o_configurator_context_t *ctx, yoml_t *node);
typedef int (*h2o_configurator_exit_cb)(h2o_configurator_t *configurator, h2o_configurator_context_t *ctx, yoml_t *node);
typedef int (*h2o_configurator_command_cb)(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node);
typedef h2o_headers_command_t **(*h2o_configurator_get_headers_commands_cb)(h2o_configurator_t *conf);

struct st_h2o_configurator_command_t {
    /**
     * configurator to which the command belongs
     */
    h2o_configurator_t *configurator;
    /**
     * name of the command handled by the configurator
     */
    const char *name;
    /**
     * flags
     */
    int flags;
    /**
     * mandatory callback called to handle the command
     */
    h2o_configurator_command_cb cb;
};

/**
 * basic structure of a configurator (handles a configuration command)
 */
struct st_h2o_configurator_t {
    h2o_linklist_t _link;
    /**
     * optional callback called when the global config is being disposed
     */
    h2o_configurator_dispose_cb dispose;
    /**
     * optional callback called before the configuration commands are handled
     */
    h2o_configurator_enter_cb enter;
    /**
     * optional callback called after all the configuration commands are handled
     */
    h2o_configurator_exit_cb exit;
    /**
     * list of commands
     */
    H2O_VECTOR(h2o_configurator_command_t) commands;
};

/**
 * registers a configurator
 */
h2o_configurator_t *h2o_configurator_create(h2o_globalconf_t *conf, size_t sz);
/**
 *
 */
void h2o_configurator_define_command(h2o_configurator_t *configurator, const char *name, int flags, h2o_configurator_command_cb cb);
/**
 * returns a configurator of given command name
 * @return configurator for given name or NULL if not found
 */
h2o_configurator_command_t *h2o_configurator_get_command(h2o_globalconf_t *conf, const char *name);
/**
 * applies the configuration to the context
 * @return 0 if successful, -1 if not
 */
int h2o_configurator_apply(h2o_globalconf_t *config, yoml_t *node, int dry_run);
/**
 *
 */
int h2o_configurator_apply_commands(h2o_configurator_context_t *ctx, yoml_t *node, int flags_mask, const char **ignore_commands);
/**
 *
 */
static int h2o_configurator_at_extension_level(h2o_configurator_context_t *ctx);
/**
 * emits configuration error
 */
void h2o_configurator_errprintf(h2o_configurator_command_t *cmd, yoml_t *node, const char *reason, ...)
    __attribute__((format(printf, 3, 4)));
/**
 * interprets the configuration value using sscanf, or prints an error upon failure
 * @param configurator configurator
 * @param node configuration value
 * @param fmt scanf-style format string
 * @return 0 if successful, -1 if not
 */
int h2o_configurator_scanf(h2o_configurator_command_t *cmd, yoml_t *node, const char *fmt, ...)
    __attribute__((format(scanf, 3, 4)));
/**
 * interprets the configuration value and returns the index of the matched string within the candidate strings, or prints an error
 * upon failure
 * @param configurator configurator
 * @param node configuration value
 * @param candidates a comma-separated list of strings (should not contain whitespaces)
 * @return index of the matched string within the given list, or -1 if none of them matched
 */
ssize_t h2o_configurator_get_one_of(h2o_configurator_command_t *cmd, yoml_t *node, const char *candidates);
/**
 * extracts values (required and optional) from a mapping by their keys, or prints an error upon failure
 * @param configurator configurator
 * @param node the mapping to parse
 * @param keys_required comma-separated list of required keys (or NULL)
 * @param keys_optional comma-separated list of optional keys (or NULL)
 * @param ... pointers to `yoml_t **` for receiving the results; they should appear in the order they appear in the key names
 * @return 0 if successful, -1 if not
 */
#define h2o_configurator_parse_mapping(cmd, node, keys_required, keys_optional, ...)                                               \
    h2o_configurator__do_parse_mapping((cmd), (node), (keys_required), (keys_optional), (yoml_t * **[]){__VA_ARGS__},              \
                                       sizeof((yoml_t ***[]){__VA_ARGS__}) / sizeof(yoml_t ***))
int h2o_configurator__do_parse_mapping(h2o_configurator_command_t *cmd, yoml_t *node, const char *keys_required,
                                       const char *keys_optional, yoml_t ****values, size_t num_values);
/**
 * returns the absolute paths of supplementary commands
 */
char *h2o_configurator_get_cmd_path(const char *cmd);

/**
 * lib/handler/configurator/headers_util.c
 */
void h2o_configurator_define_headers_commands(h2o_globalconf_t *global_conf, h2o_configurator_t *conf, const char *prefix,
                                              h2o_configurator_get_headers_commands_cb get_commands);

void h2o_configurator__init_core(h2o_globalconf_t *conf);
void h2o_configurator__dispose_configurators(h2o_globalconf_t *conf);

/* inline definitions */

inline int h2o_configurator_at_extension_level(h2o_configurator_context_t *ctx)
{
    return ctx->pathconf != NULL && ctx->pathconf->path.base == NULL && ctx->pathconf != &ctx->hostconf->fallback_path;
}

#endif

Coverage Report

Created: 2026-01-17 06:52

Line	Count	Source
1		/*
2		* Copyright (c) 2014 DeNA Co., Ltd.
3		*
4		* Permission is hereby granted, free of charge, to any person obtaining a copy
5		* of this software and associated documentation files (the "Software"), to
6		* deal in the Software without restriction, including without limitation the
7		* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8		* sell copies of the Software, and to permit persons to whom the Software is
9		* furnished to do so, subject to the following conditions:
10		*
11		* The above copyright notice and this permission notice shall be included in
12		* all copies or substantial portions of the Software.
13		*
14		* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15		* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16		* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17		* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18		* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19		* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20		* IN THE SOFTWARE.
21		*/
22		#ifndef h2o__configurator_h
23		#define h2o__configurator_h
24
25		#include "yoml.h"
26
27		enum {
28		H2O_CONFIGURATOR_FLAG_GLOBAL = 0x1,
29		H2O_CONFIGURATOR_FLAG_HOST = 0x2,
30		H2O_CONFIGURATOR_FLAG_PATH = 0x4,
31		H2O_CONFIGURATOR_FLAG_EXTENSION = 0x8,
32		H2O_CONFIGURATOR_FLAG_ALL_LEVELS =
33		H2O_CONFIGURATOR_FLAG_GLOBAL \| H2O_CONFIGURATOR_FLAG_HOST \| H2O_CONFIGURATOR_FLAG_PATH \| H2O_CONFIGURATOR_FLAG_EXTENSION,
34		H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR = 0x100,
35		H2O_CONFIGURATOR_FLAG_EXPECT_SEQUENCE = 0x200,
36		H2O_CONFIGURATOR_FLAG_EXPECT_MAPPING = 0x400,
37		H2O_CONFIGURATOR_FLAG_DEFERRED = 0x1000,
38		H2O_CONFIGURATOR_FLAG_SEMI_DEFERRED =
39		0x2000 /* used by listen, file.custom-handler (invoked before hosts,paths,file-dir, etc.) */
40		};
41
42		#define H2O_CONFIGURATOR_NUM_LEVELS 4
43
44		typedef struct st_h2o_configurator_context_t {
45		/**
46		* pointer to globalconf
47		*/
48		h2o_globalconf_t *globalconf;
49		/**
50		* pointer to hostconf, or NULL if the context is above host level
51		*/
52		h2o_hostconf_t *hostconf;
53		/**
54		* pointer to pathconf (either at path level or custom handler level), or NULL
55		*/
56		h2o_pathconf_t *pathconf;
57		/**
58		* pointer to mimemap
59		*/
60		h2o_mimemap_t **mimemap;
61		/**
62		* pointer to env
63		*/
64		h2o_envconf_t *env;
65		/**
66		* if is a dry run
67		*/
68		int dry_run;
69		/**
70		* parent context (or NULL if the context is at global level)
71		*/
72		struct st_h2o_configurator_context_t *parent;
73		} h2o_configurator_context_t;
74
75		typedef int (h2o_configurator_dispose_cb)(h2o_configurator_t configurator);
76		typedef int (h2o_configurator_enter_cb)(h2o_configurator_t configurator, h2o_configurator_context_t ctx, yoml_t node);
77		typedef int (h2o_configurator_exit_cb)(h2o_configurator_t configurator, h2o_configurator_context_t ctx, yoml_t node);
78		typedef int (h2o_configurator_command_cb)(h2o_configurator_command_t cmd, h2o_configurator_context_t ctx, yoml_t node);
79		typedef h2o_headers_command_t *(h2o_configurator_get_headers_commands_cb)(h2o_configurator_t *conf);
80
81		struct st_h2o_configurator_command_t {
82		/**
83		* configurator to which the command belongs
84		*/
85		h2o_configurator_t *configurator;
86		/**
87		* name of the command handled by the configurator
88		*/
89		const char *name;
90		/**
91		* flags
92		*/
93		int flags;
94		/**
95		* mandatory callback called to handle the command
96		*/
97		h2o_configurator_command_cb cb;
98		};
99
100		/**
101		* basic structure of a configurator (handles a configuration command)
102		*/
103		struct st_h2o_configurator_t {
104		h2o_linklist_t _link;
105		/**
106		* optional callback called when the global config is being disposed
107		*/
108		h2o_configurator_dispose_cb dispose;
109		/**
110		* optional callback called before the configuration commands are handled
111		*/
112		h2o_configurator_enter_cb enter;
113		/**
114		* optional callback called after all the configuration commands are handled
115		*/
116		h2o_configurator_exit_cb exit;
117		/**
118		* list of commands
119		*/
120		H2O_VECTOR(h2o_configurator_command_t) commands;
121		};
122
123		/**
124		* registers a configurator
125		*/
126		h2o_configurator_t h2o_configurator_create(h2o_globalconf_t conf, size_t sz);
127		/**
128		*
129		*/
130		void h2o_configurator_define_command(h2o_configurator_t configurator, const char name, int flags, h2o_configurator_command_cb cb);
131		/**
132		* returns a configurator of given command name
133		* @return configurator for given name or NULL if not found
134		*/
135		h2o_configurator_command_t h2o_configurator_get_command(h2o_globalconf_t conf, const char *name);
136		/**
137		* applies the configuration to the context
138		* @return 0 if successful, -1 if not
139		*/
140		int h2o_configurator_apply(h2o_globalconf_t config, yoml_t node, int dry_run);
141		/**
142		*
143		*/
144		int h2o_configurator_apply_commands(h2o_configurator_context_t ctx, yoml_t node, int flags_mask, const char **ignore_commands);
145		/**
146		*
147		*/
148		static int h2o_configurator_at_extension_level(h2o_configurator_context_t *ctx);
149		/**
150		* emits configuration error
151		*/
152		void h2o_configurator_errprintf(h2o_configurator_command_t cmd, yoml_t node, const char *reason, ...)
153		__attribute__((format(printf, 3, 4)));
154		/**
155		* interprets the configuration value using sscanf, or prints an error upon failure
156		* @param configurator configurator
157		* @param node configuration value
158		* @param fmt scanf-style format string
159		* @return 0 if successful, -1 if not
160		*/
161		int h2o_configurator_scanf(h2o_configurator_command_t cmd, yoml_t node, const char *fmt, ...)
162		__attribute__((format(scanf, 3, 4)));
163		/**
164		* interprets the configuration value and returns the index of the matched string within the candidate strings, or prints an error
165		* upon failure
166		* @param configurator configurator
167		* @param node configuration value
168		* @param candidates a comma-separated list of strings (should not contain whitespaces)
169		* @return index of the matched string within the given list, or -1 if none of them matched
170		*/
171		ssize_t h2o_configurator_get_one_of(h2o_configurator_command_t cmd, yoml_t node, const char *candidates);
172		/**
173		* extracts values (required and optional) from a mapping by their keys, or prints an error upon failure
174		* @param configurator configurator
175		* @param node the mapping to parse
176		* @param keys_required comma-separated list of required keys (or NULL)
177		* @param keys_optional comma-separated list of optional keys (or NULL)
178		* @param ... pointers to `yoml_t **` for receiving the results; they should appear in the order they appear in the key names
179		* @return 0 if successful, -1 if not
180		*/
181		#define h2o_configurator_parse_mapping(cmd, node, keys_required, keys_optional, ...) \
182	0	h2o_configurator__do_parse_mapping((cmd), (node), (keys_required), (keys_optional), (yoml_t * **[]){__VA_ARGS__}, \
183	0	sizeof((yoml_t *[]){__VA_ARGS__}) / sizeof(yoml_t *))
184		int h2o_configurator__do_parse_mapping(h2o_configurator_command_t cmd, yoml_t node, const char *keys_required,
185		const char keys_optional, yoml_t ***values, size_t num_values);
186		/**
187		* returns the absolute paths of supplementary commands
188		*/
189		char h2o_configurator_get_cmd_path(const char cmd);
190
191		/**
192		* lib/handler/configurator/headers_util.c
193		*/
194		void h2o_configurator_define_headers_commands(h2o_globalconf_t global_conf, h2o_configurator_t conf, const char *prefix,
195		h2o_configurator_get_headers_commands_cb get_commands);
196
197		void h2o_configurator__init_core(h2o_globalconf_t *conf);
198		void h2o_configurator__dispose_configurators(h2o_globalconf_t *conf);
199
200		/* inline definitions */
201
202		inline int h2o_configurator_at_extension_level(h2o_configurator_context_t *ctx)
203	0	{
204	0	return ctx->pathconf != NULL && ctx->pathconf->path.base == NULL && ctx->pathconf != &ctx->hostconf->fallback_path;
205	0	} Unexecuted instantiation: config.c:h2o_configurator_at_extension_level Unexecuted instantiation: configurator.c:h2o_configurator_at_extension_level Unexecuted instantiation: headers_util.c:h2o_configurator_at_extension_level Unexecuted instantiation: access_log.c:h2o_configurator_at_extension_level Unexecuted instantiation: compress.c:h2o_configurator_at_extension_level Unexecuted instantiation: errordoc.c:h2o_configurator_at_extension_level Unexecuted instantiation: expires.c:h2o_configurator_at_extension_level Unexecuted instantiation: fastcgi.c:h2o_configurator_at_extension_level Unexecuted instantiation: file.c:h2o_configurator_at_extension_level Unexecuted instantiation: h2olog.c:h2o_configurator_at_extension_level Unexecuted instantiation: headers.c:h2o_configurator_at_extension_level Unexecuted instantiation: http2_debug_state.c:h2o_configurator_at_extension_level Unexecuted instantiation: proxy.c:h2o_configurator_at_extension_level Unexecuted instantiation: redirect.c:h2o_configurator_at_extension_level Unexecuted instantiation: reproxy.c:h2o_configurator_at_extension_level Unexecuted instantiation: throttle_resp.c:h2o_configurator_at_extension_level Unexecuted instantiation: self_trace.c:h2o_configurator_at_extension_level Unexecuted instantiation: server_timing.c:h2o_configurator_at_extension_level Unexecuted instantiation: status.c:h2o_configurator_at_extension_level
206
207		#endif