From 07497205db498c9c355603d63f46f7c23c884a1e Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Mon, 2 Dec 2024 05:36:56 +0000 Subject: [PATCH 1/3] doc: add plugin output size limitation Signed-off-by: Junjie Gao --- specs/plugin-extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/plugin-extensibility.md b/specs/plugin-extensibility.md index c30c2d8..bacf468 100644 --- a/specs/plugin-extensibility.md +++ b/specs/plugin-extensibility.md @@ -120,7 +120,7 @@ Plugin config can be also set/overriden during signing with the `notation sign` ### Plugin contract -* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. +* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. The output size is limited to less than 64 MiB to avoid potential plugin unexpected behavior that triggers out-of-memory issues. * The command will be passed as the first argument to the plugin e.g. `notation-{plugin-name} `. A JSON request is passed using `stdin`. The plugin is expected to return a JSON response through `stdout` with a `0` exit code for successful response, and a non-zero exit code with a JSON error response in `stderr` for error response. Each command defines its request, response and error contract. To avoid any additional content like debug or info level logging from dependencies and inbuilt libraries, the plugin implementation should redirect any output to `stdout` on initialization, and only send the JSON response away from `stdout` when the command execution completes. E.g. For golang, set [`os.Stdout`](https://pkg.go.dev/os#pkg-variables) to point to a log file. * Every request JSON will contain a `contractVersion` top level attribute whose value will indicate the plugin contract version. Contract version is revised when there are changes to command request/response, new plugin commands are introduced, and supported through Notation. * To maintain forward compatibility plugin implementors MUST ignore unrecognized attributes in command request which are introduced in minor version updates of the plugin contract. From 6a5104f0a6333b595ae17c3069e8199dca6e7cac Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Tue, 3 Dec 2024 01:54:48 +0000 Subject: [PATCH 2/3] fix: resolve comment for Shiwei Signed-off-by: Junjie Gao --- specs/plugin-extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/plugin-extensibility.md b/specs/plugin-extensibility.md index bacf468..29bed07 100644 --- a/specs/plugin-extensibility.md +++ b/specs/plugin-extensibility.md @@ -120,7 +120,7 @@ Plugin config can be also set/overriden during signing with the `notation sign` ### Plugin contract -* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. The output size is limited to less than 64 MiB to avoid potential plugin unexpected behavior that triggers out-of-memory issues. +* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. The output size is limited to less than 64 MiB per channel to avoid potential plugin unexpected behavior that triggers out-of-memory issues. * The command will be passed as the first argument to the plugin e.g. `notation-{plugin-name} `. A JSON request is passed using `stdin`. The plugin is expected to return a JSON response through `stdout` with a `0` exit code for successful response, and a non-zero exit code with a JSON error response in `stderr` for error response. Each command defines its request, response and error contract. To avoid any additional content like debug or info level logging from dependencies and inbuilt libraries, the plugin implementation should redirect any output to `stdout` on initialization, and only send the JSON response away from `stdout` when the command execution completes. E.g. For golang, set [`os.Stdout`](https://pkg.go.dev/os#pkg-variables) to point to a log file. * Every request JSON will contain a `contractVersion` top level attribute whose value will indicate the plugin contract version. Contract version is revised when there are changes to command request/response, new plugin commands are introduced, and supported through Notation. * To maintain forward compatibility plugin implementors MUST ignore unrecognized attributes in command request which are introduced in minor version updates of the plugin contract. From 1432257aed479af84c9422bc23965c5611f76453 Mon Sep 17 00:00:00 2001 From: Junjie Gao Date: Wed, 4 Dec 2024 01:38:39 +0000 Subject: [PATCH 3/3] fix: resolve comment for Shiwei Signed-off-by: Junjie Gao --- specs/plugin-extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/plugin-extensibility.md b/specs/plugin-extensibility.md index 29bed07..889fd64 100644 --- a/specs/plugin-extensibility.md +++ b/specs/plugin-extensibility.md @@ -120,7 +120,7 @@ Plugin config can be also set/overriden during signing with the `notation sign` ### Plugin contract -* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. The output size is limited to less than 64 MiB per channel to avoid potential plugin unexpected behavior that triggers out-of-memory issues. +* Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. Currently, a size limit of less than 64 MiB is applied to each output channel for preventing out-of-memory issues of potential plugin malfunctioning. * The command will be passed as the first argument to the plugin e.g. `notation-{plugin-name} `. A JSON request is passed using `stdin`. The plugin is expected to return a JSON response through `stdout` with a `0` exit code for successful response, and a non-zero exit code with a JSON error response in `stderr` for error response. Each command defines its request, response and error contract. To avoid any additional content like debug or info level logging from dependencies and inbuilt libraries, the plugin implementation should redirect any output to `stdout` on initialization, and only send the JSON response away from `stdout` when the command execution completes. E.g. For golang, set [`os.Stdout`](https://pkg.go.dev/os#pkg-variables) to point to a log file. * Every request JSON will contain a `contractVersion` top level attribute whose value will indicate the plugin contract version. Contract version is revised when there are changes to command request/response, new plugin commands are introduced, and supported through Notation. * To maintain forward compatibility plugin implementors MUST ignore unrecognized attributes in command request which are introduced in minor version updates of the plugin contract.