可靠且快速的 NGINX 配置文件解析器。
项目描述
交叉平面
可靠且快速的 NGINX 配置文件解析器和构建器
安装
pip install crossplane
命令行界面
usage: crossplane <command> [options]
various operations for nginx config files
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
commands:
parse parses a json payload for an nginx config
build builds an nginx config from a json payload
lex lexes tokens from an nginx config file
minify removes all whitespace from an nginx config
format formats an nginx config file
help show help for commands
跨平面解析
该命令将主要 NGINX 配置文件的路径作为输入，然后将整个配置解析为下面定义的模式，并将整个内容作为 JSON 有效负载转储。
usage: crossplane parse [-h] [-o OUT] [-i NUM] [--ignore DIRECTIVES]
[--no-catch] [--tb-onerror] [--single-file]
[--include-comments] [--strict]
filename
parses a json payload for an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
--ignore DIRECTIVES ignore directives (comma-separated)
--no-catch only collect first error in file
--tb-onerror include tracebacks in config errors
--combine use includes to create one single file
--single-file do not include other config files
--include-comments include comments in json
--strict raise errors for unknown directives
隐私和安全
由于crossplane通常用于创建发送到不同服务器的有效负载，因此牢记安全性很重要。因此，--ignore添加了该选项。它可用于将某些敏感指令完全排除在有效负载输出之外。
例如，出于对用户隐私的尊重，我们总是在NGINX Amplify Agent中使用此标志的等效项：
--ignore=auth_basic_user_file,secure_link_secret,ssl_certificate_key,ssl_client_certificate,ssl_password_file,ssl_stapling_file,ssl_trusted_certificate
架构
响应对象
{
"status": String, // "ok" or "failed" if "errors" is not empty
"errors": Array, // aggregation of "errors" from Config objects
"config": Array // Array of Config objects
}
配置对象
{
"file": String, // the full path of the config file
"status": String, // "ok" or "failed" if errors is not empty array
"errors": Array, // Array of Error objects
"parsed": Array // Array of Directive objects
}
指令对象
{
"directive": String, // the name of the directive
"line": Number, // integer line number the directive started on
"args": Array, // Array of String arguments
"includes": Array, // Array of integers (included iff this is an include directive)
"block": Array // Array of Directive Objects (included iff this is a block)
}
笔记
如果这是一个include指令并且--single-file未使用标志，"includes"则将使用一个值来保存该指令包含的配置的索引数组。
如果这是一个块指令，"block"将使用一个值来保存定义块上下文的更多指令对象的数组。
错误对象
{
"file": String, // the full path of the config file
"line": Number, // integer line number the directive that caused the error
"error": String, // the error message
"callback": Object // only included iff an "onerror" function was passed to parse()
}
笔记
如果该--tb-onerror标志被跨平面解析使用，"callback"
将包含一个字符串，该字符串表示错误导致的回溯。
例子
主要的 NGINX 配置文件位于/etc/nginx/nginx.conf：
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
这个配置文件位于/etc/nginx/conf.d/servers.conf：
server {
listen 8080;
location / {
try_files 'foo bar' baz;
}
}
server {
listen 8081;
location / {
return 200 'success!';
}
}
那么如果你运行这个：
crossplane parse --indent=4 /etc/nginx/nginx.conf
美化后的 JSON 输出如下所示：
{
"status": "ok",
"errors": [],
"config": [
{
"file": "/etc/nginx/nginx.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "events",
"line": 1,
"args": [],
"block": [
{
"directive": "worker_connections",
"line": 2,
"args": [
"1024"
]
}
]
},
{
"directive": "http",
"line": 5,
"args": [],
"block": [
{
"directive": "include",
"line": 6,
"args": [
"conf.d/*.conf"
],
"includes": [
1
]
}
]
}
]
},
{
"file": "/etc/nginx/conf.d/servers.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "server",
"line": 1,
"args": [],
"block": [
{
"directive": "listen",
"line": 2,
"args": [
"8080"
]
},
{
"directive": "location",
"line": 3,
"args": [
"/"
],
"block": [
{
"directive": "try_files",
"line": 4,
"args": [
"foo bar",
"baz"
]
}
]
}
]
},
{
"directive": "server",
"line": 8,
"args": [],
"block": [
{
"directive": "listen",
"line": 9,
"args": [
"8081"
]
},
{
"directive": "location",
"line": 10,
"args": [
"/"
],
"block": [
{
"directive": "return",
"line": 11,
"args": [
"200",
"success!"
]
}
]
}
]
}
]
}
]
}
跨平面解析（高级）
此工具使用两个标志可以更改crossplane处理错误的方式。
--no-catch如果您希望 crossplane 在发现第一个错误后退出解析，则可以使用第一个。
第二个，--tb-onerror将为 JSON 输出中的所有错误对象添加一个"callback"键，每个错误对象都包含一个字符串表示，如果没有捕获异常，则解析器将引发该回溯。这对于记录目的很有用。
交叉平面构建
此命令将文件路径作为输入。该文件应包含具有上述结构的 NGINX 配置的 JSON 表示。保存和使用输出crossplane parse来重建您的配置文件不应导致除格式之外的任何内容差异。
usage: crossplane build [-h] [-d PATH] [-f] [-i NUM | -t] [--no-headers]
[--stdout] [-v]
filename
builds an nginx config from a json payload
positional arguments:
filename the file with the config payload
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-d PATH, --dir PATH the base directory to build in
-f, --force overwrite existing files
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
--no-headers do not write header to configs
--stdout write configs to stdout instead
交叉平面法
该命令采用 NGINX 配置文件，通过删除空格和注释将其拆分为标记，并将标记列表转储为 JSON 数组。
usage: crossplane lex [-h] [-o OUT] [-i NUM] [-n] filename
lexes tokens from an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-n, --line-numbers include line numbers in json payload
例子
在以下位置传递此 NGINX 配置文件/etc/nginx/nginx.conf：
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
通过运行：
crossplane lex /etc/nginx/nginx.conf
将导致此 JSON 输出：
["events","{","worker_connections","1024",";","}","http","{","include","conf.d/*.conf",";","}"]
但是，如果您决定使用该--line-numbers标志，您的输出将如下所示：
[["events",1],["{",1],["worker_connections",2],["1024",2],[";",2],["}",3],["http",5],["{",5],["include",6],["conf.d/*.conf",6],[";",6],["}",7]]
交叉平面格式
这是一个快速而肮脏的工具，它在内部使用跨平面解析来格式化 NGINX 配置文件。它的目的是展示您可以使用crossplane的解析能力做什么。它并不是一个完整的、功能丰富的格式化工具。如果那是您正在寻找的，那么您可能希望使用 crossplane 的 Python API 编写自己的代码。
usage: crossplane format [-h] [-o OUT] [-i NUM | -t] filename
formats an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
交叉平面缩小
这是一个简单而有趣的小工具，它在内部使用crossplane lex从 NGINX 配置文件中删除尽可能多的空白而不影响它的作用。它无法想象它会对大多数人有多大用处，但它展示了您可以使用crossplane的词法分析能力做的各种事情。
usage: crossplane minify [-h] [-o OUT] filename
removes all whitespace from an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
Python 模块
除了命令行工具，您还可以导入crossplane为 python 模块。该模块将为您提供两个基本功能：parse和lex.
crossplane.parse()
import crossplane
payload = crossplane.parse('/etc/nginx/nginx.conf')
这将返回与跨平面解析部分中描述的相同的有效负载，除了它将是 Python dicts 而不是一个巨大的 JSON 字符串。
crossplane.build()
import crossplane
config = crossplane.build(
[{
"directive": "events",
"args": [],
"block": [{
"directive": "worker_connections",
"args": ["1024"]
}]
}]
)
这将返回一个包含整个 NGINX 配置文件的字符串。
crossplane.lex()
import crossplane
tokens = crossplane.lex('/etc/nginx/nginx.conf')
crossplane.lex生成 2 元组。将这些对插入到列表中将产生一个长列表，类似于使用标志时在
crossplane lex部分中看到的--line-numbers内容，不同之处在于它显然是一个 Python 元组列表，而不是一个巨大的 JSON 字符串。
