From e0c15ae4575335fb079e2d33fc853a547b2380c9 Mon Sep 17 00:00:00 2001 From: Ava Hahn Date: Fri, 14 Jun 2024 21:04:15 -0700 Subject: tools/unitctl: implement application subcommand * application subcommand UI schema * application subcommand handler * additions to unit-client-rs to expose application API * elaborate on OpenAPI error handling * adds wasm and wasi app schemas to OpenAPI Schema * updates tools/unitctl OpenAPI library * many linter fixes * README.md updates Signed-off-by: Ava Hahn --- docs/unit-openapi.yaml | 85 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) (limited to 'docs/unit-openapi.yaml') diff --git a/docs/unit-openapi.yaml b/docs/unit-openapi.yaml index b2e02e89..f69e615c 100644 --- a/docs/unit-openapi.yaml +++ b/docs/unit-openapi.yaml @@ -4730,6 +4730,9 @@ components: isolation: rootfs: "/www/" + wasiapp: + type: "wasm-wasi-component" + # /config/listeners configListeners: summary: "Multiple listeners" @@ -5304,6 +5307,8 @@ components: - $ref: "#/components/schemas/configApplicationPHP" - $ref: "#/components/schemas/configApplicationPython" - $ref: "#/components/schemas/configApplicationRuby" + - $ref: "#/components/schemas/configApplicationWasm" + - $ref: "#/components/schemas/configApplicationWasi" discriminator: propertyName: type @@ -5314,6 +5319,8 @@ components: php: "#/components/schemas/configApplicationPHP" python: "#/components/schemas/configApplicationPython" ruby: "#/components/schemas/configApplicationRuby" + wasm: "#/components/schemas/configApplicationWasm" + wasm-wasi-component: "#/components/schemas/configApplicationWasi" # ABSTRACT BASE SCHEMA, NOT PRESENT IN THE CONFIGURATION; STORES COMMON OPTIONS configApplicationCommon: @@ -5326,7 +5333,7 @@ components: type: type: string description: "Application type and language version." - enum: [external, java, perl, php, python, ruby] + enum: [external, java, perl, php, python, ruby, wasm, wasm-wasi-component] environment: type: object @@ -5592,6 +5599,82 @@ components: description: "Number of worker threads per app process." default: 1 + configApplicationWasm: + description: "WASM application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - module + - request_handler + - malloc_handler + - free_handler + + properties: + module: + type: string + description: "Path to WebAssembly module." + + request_handler: + type: string + description: "Name of request handling function." + + malloc_handler: + type: string + description: "Name of memory allocator function." + + free_handler: + type: string + description: "Name of memory free function." + + access: + type: object + properties: + filesystem: + $ref: "#/components/schemas/stringArray" + description: "Host directories this application may have access to." + + module_init_handler: + type: string + description: "Name of function called to initialize module." + + module_end_handler: + type: string + description: "Name of function called to teardown module." + + request_init_handler: + type: string + description: "Name of function called to initialize request." + + request_end_handler: + type: string + description: "Name of function called to teardown request." + + response_end_handler: + type: string + description: "Name of function called to teardown response." + + + configApplicationWasi: + description: "WASI application on Unit." + allOf: + - $ref: "#/components/schemas/configApplicationCommon" + - type: object + required: + - component + + properties: + component: + type: string + description: "Path to wasm wasi component application." + + access: + type: object + properties: + filesystem: + $ref: "#/components/schemas/stringArray" + description: "Host directories this application may have access to." + configApplicationPHP: description: "PHP application on Unit." allOf: -- cgit From 11a70a321f70d3729d3893751000bc4f036a182f Mon Sep 17 00:00:00 2001 From: Jon Torre Date: Thu, 1 Aug 2024 14:51:01 +0100 Subject: docs/openapi: Update the /status endpoint URL This was renamed to be more accurate as /status is not just about statistics, as it also now shows the loaded language modules. [ Commit message - Andrew ] Signed-off-by: Andrew Clayton --- docs/unit-openapi.yaml | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/unit-openapi.yaml') diff --git a/docs/unit-openapi.yaml b/docs/unit-openapi.yaml index f69e615c..6bb5a17f 100644 --- a/docs/unit-openapi.yaml +++ b/docs/unit-openapi.yaml @@ -3906,7 +3906,7 @@ paths: operationId: getStatus summary: "Retrieve the status object" description: "Retrieves the entire `/status` section that represents - Unit's [usage statistics](https://unit.nginx.org/usagestats/)." + Unit's [usage statistics and list of loaded modules](https://unit.nginx.org/statusapi/)." tags: - status @@ -3930,7 +3930,7 @@ paths: operationId: getStatusConnections summary: "Retrieve the connections status object" description: "Retrieves the `connections` status object that represents - Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + Unit's [connection statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -3955,7 +3955,7 @@ paths: operationId: getStatusConnectionsAccepted summary: "Retrieve the accepted connections number" description: "Retrieves the `accepted` connections number that represents - Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + Unit's [connection statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -3979,7 +3979,7 @@ paths: operationId: getStatusConnectionsActive summary: "Retrieve the active connections number" description: "Retrieves the `active` connections number that represents - Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + Unit's [connection statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4003,7 +4003,7 @@ paths: operationId: getStatusConnectionsIdle summary: "Retrieve the idle connections number" description: "Retrieves the `idle` connections number that represents - Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + Unit's [connection statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4026,7 +4026,7 @@ paths: operationId: getStatusConnectionsClosed summary: "Retrieve the closed connections number" description: "Retrieves the `closed` connections number that represents - Unit's [connection statistics](https://unit.nginx.org/usagestats/)." + Unit's [connection statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4051,7 +4051,7 @@ paths: summary: "Retrieve the requests status object" description: "Retrieves the `requests` status object that represents Unit's instance [request statistics] - (https://unit.nginx.org/usagestats/)." + (https://unit.nginx.org/statusapi/)." tags: - status @@ -4075,7 +4075,7 @@ paths: operationId: getStatusRequestsTotal summary: "Retrieve the total requests number" description: "Retrieves the `total` requests number that represents Unit's - instance [request statistics](https://unit.nginx.org/usagestats/)." + instance [request statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4100,7 +4100,7 @@ paths: summary: "Retrieve the applications status object" description: "Retrieves the `applications` status object that represents Unit's per-app - [process and request statistics](https://unit.nginx.org/usagestats/)." + [process and request statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4125,7 +4125,7 @@ paths: summary: "Retrieve the app status object" description: "Retrieves the app status object that represents Unit's per-app - [process and request statistics](https://unit.nginx.org/usagestats/)." + [process and request statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4156,7 +4156,7 @@ paths: summary: "Retrieve the processes app status object" description: "Retrieves the `processes` app status object that represents Unit's per-app - [process statistics](https://unit.nginx.org/usagestats/)." + [process statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4186,7 +4186,7 @@ paths: summary: "Retrieve the running processes app status number" description: "Retrieves the `running` processes number that represents Unit's per-app - [process statistics](https://unit.nginx.org/usagestats/)." + [process statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4217,7 +4217,7 @@ paths: summary: "Retrieve the starting processes app status number" description: "Retrieves the `starting` processes number that represents Unit's per-app - [process statistics](https://unit.nginx.org/usagestats/)." + [process statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4248,7 +4248,7 @@ paths: summary: "Retrieve the idle processes app status number" description: "Retrieves the `idle` processes number that represents Unit's per-app - [process statistics](https://unit.nginx.org/usagestats/)." + [process statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4278,7 +4278,7 @@ paths: summary: "Retrieve the requests app status object" description: "Retrieves the `requests` app status object that represents Unit's per-app - [request statistics](https://unit.nginx.org/usagestats/)." + [request statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -4306,7 +4306,7 @@ paths: summary: "Retrieve the active requests app status number" description: "Retrieves the `active` requests number that represents Unit's per-app - [request statistics](https://unit.nginx.org/usagestats/)." + [request statistics](https://unit.nginx.org/statusapi/)." tags: - status @@ -6455,7 +6455,7 @@ tags: - name: status description: Everything about the /status section in Unit's control API externalDocs: - url: https://unit.nginx.org/usagestats/ + url: https://unit.nginx.org/statusapi/ - name: tls description: Everything about SSL/TLS in Unit's control API -- cgit From ae4795aa182a27fb1b091670f4831e345614a09c Mon Sep 17 00:00:00 2001 From: Jon Torre Date: Thu, 1 Aug 2024 14:55:43 +0100 Subject: docs/openapi: Add entries for the new /status/modules endpoint Unit now shows the loaded language modules under /status/modules. This functionality was added in commit 707f4ef82 ("status: Show list of loaded language modules"). [ Commit message - Andrew ] Co-developed-by: Andrew Clayton Signed-off-by: Andrew Clayton --- docs/unit-openapi.yaml | 178 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 1 deletion(-) (limited to 'docs/unit-openapi.yaml') diff --git a/docs/unit-openapi.yaml b/docs/unit-openapi.yaml index 6bb5a17f..6c4d4e00 100644 --- a/docs/unit-openapi.yaml +++ b/docs/unit-openapi.yaml @@ -3924,6 +3924,114 @@ paths: example1: $ref: "#/components/examples/status" + /status/modules: + summary: "Endpoint for the `modules` status object" + get: + operationId: getStatusModules + summary: "Retrieve the modules status object" + description: "Retrieves the `modules` status object that represents + Unit's [loaded language modules](https://unit.nginx.org/statusapi/)." + + tags: + - status + + responses: + "200": + description: "OK; the `modules` object exists in the configuration." + + content: + application/json: + schema: + $ref: "#/components/schemas/statusModules" + + examples: + example1: + $ref: "#/components/examples/statusModules" + + example2: + $ref: "#/components/examples/statusModulesArray" + + /status/modules/{langMod}: + summary: "Endpoint for the loaded language `module` object" + get: + operationId: getStatusModulesLang + summary: "Retrieve the language module object" + description: "Retrieves the language `module` object that represents a + currently loaded language module." + + tags: + - status + + responses: + "200": + description: "OK; the language `module` object exists." + + content: + application/json: + schema: + $ref: "#/components/schemas/StatusModulesLang" + + examples: + example1: + $ref: "#/components/examples/statusModulesLang + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/modules/{langMod}/version: + summary: "Endpoint for the loaded language module `version` object" + get: + operationId: getStatusModulesLangVersion + summary: "Retrieve the language module version object" + description: "Retrieves the language module `version` object that + represents the version of a currently loaded language module." + + tags: + - status + + responses: + "200": + description: "OK; the language module `version` object exists." + + content: + application/json: + schema: + $ref: "#/components/schemas/StatusModulesLangVersion" + + examples: + example1: + $ref: "#/components/examples/statusModulesLangVersion + + "404": + $ref: "#/components/responses/responseNotFound" + + /status/modules/{langMod}/lib: + summary: "Endpoint for the loaded language module `lib` object" + get: + operationId: getStatusModulesLangLib + summary: "Retrieves the language module lib object" + description: "Retrieves the language module `lib` object that represents + the file path to the loaded language module." + + tags: + - status + + responses: + "200": + description: "OK; the language module `lib` object exists." + + content: + application/json: + schema: + $ref: "#/components/schemas/StatusModulesLangLib" + + examples: + example1: + $ref: "#/components/examples/statusModulesLangLib + + "404": + $ref: "#/components/responses/responseNotFound" + /status/connections: summary: "Endpoint for the `connections` status object" get: @@ -4993,6 +5101,10 @@ components: status: summary: "Regular status object" value: + modules: + php: + version: "8.3.4" + lib: "/opt/unit/modules/php.unit.so" connections: accepted: 1067 active: 13 @@ -5009,6 +5121,45 @@ components: requests: active: 15 + # /status/modules + statusModules: + summary: "Loaded language modules status object" + value: + php: + version: "8.3.4" + lib: "/opt/unit/modules/php.unit.so" + + statusModulesArray: + summary: "Loaded language modules status array" + value: + php: + version: "8.3.4" + lib: "/opt/unit/modules/php.unit.so" + python: + - { version: "3.12.3", lib: "/opt/unit/modules/python.unit.so" } + - { version: "3.11.1", lib: "/opt/unit/modules/python-3.11.1.unit.so" } + wasm: + version: "0.2" + lib: "/opt/unit/modules/wasm.unit.so" + + # /status/modules/{langMod} + statusModulesLang: + summary: "Object or array of objects of specified language module" + value: + python: + version: "3.12.3" + lib: "/opt/unit/modules/python.unit.so" + + # /status/modules/{langMod}/version + statusModulesLangVersion: + summary: "String describing the version of the language module" + value: "3.12.3" + + # /status/modules/{langMod}/lib + statusModulesLangLib: + summary: "String describing the path to the loaded language module" + value: "/opt/unit/modules/python.unit.so" + # /status/connections statusConnections: summary: "Regular connections status object" @@ -6319,9 +6470,13 @@ components: # /status status: - description: "Represents Unit's usage statistics." + description: "Represents Unit's loaded language modules and usage + statistics." type: object properties: + modules: + $ref: "#/components/schemas/statusModules" + connections: $ref: "#/components/schemas/statusConnections" @@ -6331,6 +6486,27 @@ components: applications: $ref: "#/components/schemas/statusApplications" + # /status/modules + statusModules: + description: "Lists currently loaded language modules." + type: object + + # /status/modules/{langMod} + statusModulesLang: + description: "Lists currently loaded versions of the specified language + module." + type: array or object + + # /status/modules/{langMod}/version + statusModulesLangVersion: + description: "Describes the version of the specified language module." + type: string + + # /status/modules/{langMod}/lib + statusModulesLangLib: + description: "Describes the path to the specified language module." + type: string + # /status/applications statusApplications: description: "Lists Unit's application process and request statistics." -- cgit From 05b1c769735667be8ad4a105296eb072f6f58076 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 20 Aug 2024 19:43:19 +0100 Subject: docs/openapi: Fix brokenness - Missing end quotes - Wrong indentation - Missing langMod parameter definition - Wrong type specification Fixes: ae4795aa1 ("docs/openapi: Add entries for the new /status/modules endpoint") Signed-off-by: Andrew Clayton --- docs/unit-openapi.yaml | 105 +++++++++++++++++++++++++++++-------------------- 1 file changed, 62 insertions(+), 43 deletions(-) (limited to 'docs/unit-openapi.yaml') diff --git a/docs/unit-openapi.yaml b/docs/unit-openapi.yaml index 6c4d4e00..9a2c7ec8 100644 --- a/docs/unit-openapi.yaml +++ b/docs/unit-openapi.yaml @@ -3959,24 +3959,27 @@ paths: description: "Retrieves the language `module` object that represents a currently loaded language module." - tags: - - status + tags: + - status - responses: - "200": - description: "OK; the language `module` object exists." + parameters: + - $ref: "#/components/parameters/langMod" - content: - application/json: - schema: - $ref: "#/components/schemas/StatusModulesLang" + responses: + "200": + description: "OK; the language `module` object exists." - examples: - example1: - $ref: "#/components/examples/statusModulesLang + content: + application/json: + schema: + $ref: "#/components/schemas/statusModulesLang" - "404": - $ref: "#/components/responses/responseNotFound" + examples: + example1: + $ref: "#/components/examples/statusModulesLang" + + "404": + $ref: "#/components/responses/responseNotFound" /status/modules/{langMod}/version: summary: "Endpoint for the loaded language module `version` object" @@ -3986,24 +3989,27 @@ paths: description: "Retrieves the language module `version` object that represents the version of a currently loaded language module." - tags: - - status + tags: + - status - responses: - "200": - description: "OK; the language module `version` object exists." + parameters: + - $ref: "#/components/parameters/langMod" - content: - application/json: - schema: - $ref: "#/components/schemas/StatusModulesLangVersion" + responses: + "200": + description: "OK; the language module `version` object exists." - examples: - example1: - $ref: "#/components/examples/statusModulesLangVersion + content: + application/json: + schema: + $ref: "#/components/schemas/statusModulesLangVersion" - "404": - $ref: "#/components/responses/responseNotFound" + examples: + example1: + $ref: "#/components/examples/statusModulesLangVersion" + + "404": + $ref: "#/components/responses/responseNotFound" /status/modules/{langMod}/lib: summary: "Endpoint for the loaded language module `lib` object" @@ -4013,24 +4019,27 @@ paths: description: "Retrieves the language module `lib` object that represents the file path to the loaded language module." - tags: - - status + tags: + - status - responses: - "200": - description: "OK; the language module `lib` object exists." + parameters: + - $ref: "#/components/parameters/langMod" - content: - application/json: - schema: - $ref: "#/components/schemas/StatusModulesLangLib" + responses: + "200": + description: "OK; the language module `lib` object exists." - examples: - example1: - $ref: "#/components/examples/statusModulesLangLib + content: + application/json: + schema: + $ref: "#/components/schemas/statusModulesLangLib" + + examples: + example1: + $ref: "#/components/examples/statusModulesLangLib" - "404": - $ref: "#/components/responses/responseNotFound" + "404": + $ref: "#/components/responses/responseNotFound" /status/connections: summary: "Endpoint for the `connections` status object" @@ -4474,6 +4483,14 @@ components: schema: type: string + langMod: + in: path + description: "A language modules name in the modules status." + name: langMod + required: true + schema: + type: string + listenerName: in: path description: "Listener name; a unique combination of a host IP address @@ -6495,7 +6512,9 @@ components: statusModulesLang: description: "Lists currently loaded versions of the specified language module." - type: array or object + oneOf: + - type: string + - type: object # /status/modules/{langMod}/version statusModulesLangVersion: -- cgit From cff18f898f58786bc003dbe2921bc0197cc58887 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Wed, 21 Aug 2024 16:37:35 +0100 Subject: docs/openapi: Add new config options Add entries for the new 'backlog' and 'listen_threads' config options introduced in commits 57c88fd40 ("router: Make the number of router threads configurable") and 76489fb7e ("conf, router: Make the listen(2) backlog configurable"). Signed-off-by: Andrew Clayton --- docs/unit-openapi.yaml | 152 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) (limited to 'docs/unit-openapi.yaml') diff --git a/docs/unit-openapi.yaml b/docs/unit-openapi.yaml index 9a2c7ec8..3acc1416 100644 --- a/docs/unit-openapi.yaml +++ b/docs/unit-openapi.yaml @@ -2791,6 +2791,72 @@ paths: "404": $ref: "#/components/responses/responseNotFound" + /config/listeners/{listenerName}/backlog: + summary: "Endpoint for the `listeners/{listenerName}/backlog` option" + get: + operationId: getListenerBacklog + summary: "Retrieve the backlog option in a listener" + description: "Retrieves the `backlog` option that configures the + listen(2) backlog parameter where the `{listenerName}` listener object + [passes its requests](https://unit.nginx.org/configuration/#listeners)." + + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + responses: + "200": + description: "OK; the `backlog` option exists in the configuration." + content: + application/json: + schema: + type: integer + + examples: + example1: + $ref: "#/components/examples/configListenerBacklog" + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateListenerBacklog + summary: "Update the backlog option in a listener" + description: "Overwrites the `backlog` option." + tags: + - listeners + - config + + parameters: + - $ref: "#/components/parameters/listenerName" + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + example1: + $ref: "#/components/examples/configListenerBacklog" + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + /config/routes: summary: "Endpoint for the `routes` entity in the configuration" get: @@ -2943,6 +3009,87 @@ paths: "404": $ref: "#/components/responses/responseNotFound" + /config/settings/listen_threads: + summary: "Endpoint for the `listen_threads` option in `settings`" + get: + operationId: getSettingsListenThreads + summary: "Retrieve the listen_threads option from settings" + description: "Retrieves the `listen_threads` option that represents + Unit's [listen threads] + (https://unit.nginx.org/configuration/#settings)." + + tags: + - settings + - config + + responses: + "200": + description: "OK; the `listen_threads` option exists in the + configuration." + + content: + application/json: + schema: + type: integer + + examples: + ListenThreads: + value: 16 + + "404": + $ref: "#/components/responses/responseNotFound" + + put: + operationId: updateSettingsListenThreads + summary: "Create or overwrite the listen_threads option" + description: "Creates or overwrites the `listen_threads` option in + the configuration." + + tags: + - settings + - config + + requestBody: + required: true + content: + application/json: + schema: + type: integer + + examples: + ListenThreads: + value: 30 + + responses: + "200": + $ref: "#/components/responses/responseOkUpdated" + + "400": + $ref: "#/components/responses/responseBadRequest" + + "404": + $ref: "#/components/responses/responseNotFound" + + "500": + $ref: "#/components/responses/responseInternalError" + + delete: + operationId: deleteSettingsListenThreads + summary: "Delete the listen_threads option" + description: "Deletes the `listen_threads` option from the + configuration." + + tags: + - settings + - config + + responses: + "200": + $ref: "#/components/responses/responseOkDeleted" + + "404": + $ref: "#/components/responses/responseNotFound" + /config/settings/http: summary: "Endpoint for the `http` object in `settings`" @@ -4961,6 +5108,11 @@ components: summary: "App target destination in a listener" value: "applications/php_app/index_target" + # /config/listeners/listenerName}/backlog + configListenerBacklog: + summary: "listen(2) backlog in a listener" + value: 1024 + # /config/listeners/{listenerName}/tls configListenerTls: summary: "TLS object in a listener" -- cgit