《深入理解ngx》—— 模块基础
1. configure 添加模块
1.1 添加一个 http 模块
在./src/test下创建config
内容如下
# 定义模块名称
1 ngx_addon_name=ngx_http_test_module
# 向http类添加 新模块
2 HTTP_MODULES="$HTTP_MODULES ngx_http_test_module"
# 添加源文件
3 NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_test_module.c"
如果添加过滤模块则为
2 HTTP_FILTER_MODULES="$HTTP_FILTER_MODULES ngx_http_test_module"
1.2 原理分析
1.2.1 加载config配置
--add-module就是 设置 NGX_ADDONS,
并且一次只能设置一个，所以要添加多个模块，需要使用多个 --add-module
343 --add-module=*) NGX_ADDONS="$NGX_ADDONS $value" ;;
当 NGX_ADDONS 不为空，则加载相关 config ，以设置变量
1197 if test -n "$NGX_ADDONS"; then
1198
1199 echo configuring additional modules
1200
1201 for ngx_addon_dir in $NGX_ADDONS
1202 do
1203 echo "adding module in $ngx_addon_dir"
1204
1205 ngx_module_type=
1206 ngx_module_name=
1207 ngx_module_incs=
1208 ngx_module_deps=
1209 ngx_module_srcs=
1210 ngx_module_libs=
1211 ngx_module_order=
1212 ngx_module_link=ADDON
1213
1214 if test -f $ngx_addon_dir/config; then
1215 . $ngx_addon_dir/config
1216
1217 echo " + $ngx_addon_name was configured"
1218
1219 else
1220 echo "$0: error: no $ngx_addon_dir/config was found"
1221 exit 1
1222 fi
1223 done
1224 fi
1.2.2 生成ngx_modules.c
1286 modules="$CORE_MODULES $EVENT_MODULES"
1295 if [ $HTTP = YES ]; then
1296 modules="$modules $HTTP_MODULES $HTTP_FILTER_MODULES \
1297 $HTTP_AUX_FILTER_MODULES $HTTP_INIT_FILTER_MODULES"
1298
1299 NGX_ADDON_DEPS="$NGX_ADDON_DEPS \$(HTTP_DEPS)"
1300 fi
1301
1383 cat << END > $NGX_MODULES_C
1384
1385 #include <ngx_config.h>
1386 #include <ngx_core.h>
1387
1388 $NGX_PRAGMA
1389
1390 END
1391
1392 for mod in $modules
1393 do
1394 echo "extern ngx_module_t $mod;" >> $NGX_MODULES_C
1395 done
1396
1397 echo >> $NGX_MODULES_C
1398 echo 'ngx_module_t *ngx_modules[] = {' >> $NGX_MODULES_C
1399
1400 for mod in $modules
1401 do
1402 echo " &$mod," >> $NGX_MODULES_C
1403 done
1404
1405 cat << END >> $NGX_MODULES_C
1406 NULL
1407 };
1408
1409 END
1410
1411 echo 'char *ngx_module_names[] = {' >> $NGX_MODULES_C
1412
1413 for mod in $modules
1414 do
1415 echo " \"$mod\"," >> $NGX_MODULES_C
1416 done
1417
1418 cat << END >> $NGX_MODULES_C
1419 NULL
1420 };
1421
1422 END
1.2.4 生成makefile
生成编译make
407 # the addons sources
408
409 if test -n "$NGX_ADDON_SRCS"; then
410
411 ngx_cc="\$(CC) $ngx_compile_opt \$(CFLAGS) $ngx_use_pch \$(ALL_INCS)"
412
413 for ngx_src in $NGX_ADDON_SRCS
414 do
415 ngx_obj="addon/`basename \`dirname $ngx_src\``"
416
417 ngx_obj=`echo $ngx_obj/\`basename $ngx_src\` \
418 | sed -e "s/\//$ngx_regex_dirsep/g"`
419
420 ngx_obj=`echo $ngx_obj \
421 | sed -e "s#^\(.*\.\)cpp\\$#$ngx_objs_dir\1$ngx_objext#g" \
422 -e "s#^\(.*\.\)cc\\$#$ngx_objs_dir\1$ngx_objext#g" \
423 -e "s#^\(.*\.\)c\\$#$ngx_objs_dir\1$ngx_objext#g" \
424 -e "s#^\(.*\.\)S\\$#$ngx_objs_dir\1$ngx_objext#g"`
425
426 ngx_src=`echo $ngx_src | sed -e "s/\//$ngx_regex_dirsep/g"`
427
428 cat << END >> $NGX_MAKEFILE
429
430 $ngx_obj: \$(ADDON_DEPS)$ngx_cont$ngx_src
431 $ngx_cc$ngx_tab$ngx_objout$ngx_obj$ngx_tab$ngx_src$NGX_AUX
432
433 END
434 done
435
436 fi
1.2.5 生成链接
225 cat << END >> $NGX_MAKEFILE
226
227 build: binary modules manpage
228
229 binary: $NGX_OBJS${ngx_dirsep}nginx$ngx_binext
230
231 $NGX_OBJS${ngx_dirsep}nginx$ngx_binext: $ngx_deps$ngx_spacer
232 \$(LINK) $ngx_long_start$ngx_binout$NGX_OBJS${ngx_dirsep}nginx$ngx_binext$n gx_long_cont$ngx_objs$ngx_libs$ngx_link$ngx_main_link
233 $ngx_rcc
234 $ngx_long_end
235
236 modules:
237 END
2. 模块基础
2.0 ngx_module
222 struct ngx_module_s {
223 ngx_uint_t ctx_index; // index in similar modules
224 ngx_uint_t index; // index in ngx_module array
225
226 char *name;
227
228 ngx_uint_t spare0;
229 ngx_uint_t spare1;
230
231 ngx_uint_t version;
232 const char *signature;
233
234 void *ctx; // to fork different types of module
235 ngx_command_t *commands; // commands of module
236 ngx_uint_t type; // NGX_HTTP_MODULE | NGX_CORE_MODULE | NGX_EVENT_MODULE | NGX_MAIL_MODULE
237
238 ngx_int_t (*init_master)(ngx_log_t *log);
239
240 ngx_int_t (*init_module)(ngx_cycle_t *cycle);
241
242 ngx_int_t (*init_process)(ngx_cycle_t *cycle);
243 ngx_int_t (*init_thread)(ngx_cycle_t *cycle);
244 void (*exit_thread)(ngx_cycle_t *cycle);
245 void (*exit_process)(ngx_cycle_t *cycle);
246
247 void (*exit_master)(ngx_cycle_t *cycle);
248
249 uintptr_t spare_hook0;
250 uintptr_t spare_hook1;
251 uintptr_t spare_hook2;
252 uintptr_t spare_hook3;
253 uintptr_t spare_hook4;
254 uintptr_t spare_hook5;
255 uintptr_t spare_hook6;
256 uintptr_t spare_hook7;
257 };
比较重要的属性是 ctx 和 commands
ctx用于派生具体的模块，
commands 定义模块支持的指令
2.1 ngx_http_module_t
定义http模块时， ngx_module_t->ctx 为 ngx_http_module_t
24 typedef struct {
25 ngx_int_t (*preconfiguration)(ngx_conf_t *cf);
26 ngx_int_t (*postconfiguration)(ngx_conf_t *cf);
27
28 void *(*create_main_conf)(ngx_conf_t *cf);
29 char *(*init_main_conf)(ngx_conf_t *cf, void *conf);
30
31 void *(*create_srv_conf)(ngx_conf_t *cf);
32 char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf);
33
34 void *(*create_loc_conf)(ngx_conf_t *cf);
35 char *(*merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf);
36 } ngx_http_module_t;
2.2 struct ngx_commands_s
77 struct ngx_command_s {
78 ngx_str_t name;
79 ngx_uint_t type; // set the area of command appears
80 char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
81 ngx_uint_t conf; // offset of cfg context
82 ngx_uint_t offset; // offset of user cfg struct
83 void *post; // the processing method after reading command
84 };
2.3 简单的http模块
以access模块为例
68 static ngx_command_t ngx_http_access_commands[] = {
69
70 { ngx_string("allow"),
71 NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_HTTP_LMT_CONF
72 |NGX_CONF_TAKE1,
73 ngx_http_access_rule,
/*
由于conf为loc级别，所以处理请求时，使用如下获得配置
133 alcf = ngx_http_get_module_loc_conf(r, ngx_http_access_module);
并且 ngx_http_access_rule ，的conf参数，被传入 loc级别配置
295 static char *
296 ngx_http_access_rule(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
297 {
298 ngx_http_access_loc_conf_t *alcf = conf;
*/
74 NGX_HTTP_LOC_CONF_OFFSET,
75 0,
76 NULL },
77
86 ngx_null_command
87 };
定义http模块上下文
91 static ngx_http_module_t ngx_http_access_module_ctx = {
92 NULL, /* preconfiguration */
/*
所有配置解析完成后调用 ngx_http_access_init
*/
93 ngx_http_access_init, /* postconfiguration */
94
95 NULL, /* create main configuration */
96 NULL, /* init main configuration */
97
98 NULL, /* create server configuration */
99 NULL, /* merge server configuration */
100
101 ngx_http_access_create_loc_conf, /* create location configuration */
102 ngx_http_access_merge_loc_conf /* merge location configuration */
103 };
绑定处理函数和处理阶段
447 static ngx_int_t
448 ngx_http_access_init(ngx_conf_t *cf)
449 {
450 ngx_http_handler_pt *h;
451 ngx_http_core_main_conf_t *cmcf;
452
453 cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
454
455 h = ngx_array_push(&cmcf->phases[NGX_HTTP_ACCESS_PHASE].handlers);
456 if (h == NULL) {
457 return NGX_ERROR;
458 }
459
460 *h = ngx_http_access_handler;
461
462 return NGX_OK;
463 }
处理请求时，先获得配置，根据配置处理请求
122 static ngx_int_t
123 ngx_http_access_handler(ngx_http_request_t *r)
124 {
126 ngx_http_access_loc_conf_t *alcf;
133 alcf = ngx_http_get_module_loc_conf(r, ngx_http_access_module);
模块返回给ngx，通常表示如下
NGX_OK : 本阶段处理通过，交给下个阶段模块处理
NGX_DECLINED : 本模块通过，交给本阶段下个模块处理。若本阶段所有模块都处理完了，交给下个阶段模块处理
还可以返回响应码，直接响应，不再处理
NGX_HTTP_OK
NGX_HTTP_FORBIDDEN
NGX_HTTP_NOT_FOUND
ngx对返回值的处理，需要具体分析对应的 checker 函数。
2.4 请求上下文
每个请求都不同，模块可以为请求建立一个请求会话——请求上下文。
请求上下文是挂载在 ngx_http_request_t->ctx上的，
371 struct ngx_http_request_s {
376 void **ctx; // request ctx
使用如下宏设置和获得
75 #define ngx_http_get_module_ctx(r, module) (r)->ctx[module.ctx_index]
76 #define ngx_http_set_ctx(r, c, module) r->ctx[module.ctx_index] = c;
示例，首次获得请求时，检查ctx是否设置，若未设置，则使用 r->pool分配请求上下文，后设置
115 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_addition_ctx_t));
116 if (ctx == NULL) {
117 return NGX_ERROR;
118 }
119
120 ngx_http_set_ctx(r, ctx, ngx_http_addition_filter_module);
2.4 总结
通过模块机制，可以：
1）定义配置指令
2）定义配置上下文，根据指令解析，对配置上下文赋值
3）挂载请求处理函数
4）处理请求时，根据 模块idx，获得模块的 配置上下文，根据配置上下文解析配置。
5）分配请求上下文，维护生命周期为单个请求的数据，以处理请求。
