diff --git a/feature/gnoi/system/tests/gnoi_file_conformance_test/README.md b/feature/gnoi/system/tests/gnoi_file_conformance_test/README.md new file mode 100644 index 00000000000..18a291edc96 --- /dev/null +++ b/feature/gnoi/system/tests/gnoi_file_conformance_test/README.md @@ -0,0 +1,613 @@ +# gNOI-5.4: gNOI File Put and Stat Protocol Conformance + +## Summary + +* **Objective**: Validate OpenConfig `gnoi.file.File` (`Put`, `Stat`, `Get`, + `Remove`, and `TransferToRemote`) protocol conformance, mandatory trailing + `types.HashType` stream validation (`SHA256`, `MD5`, and rejection of + `UNSPECIFIED`), fixed-length unsigned hex digest formatting across high-bit + (`>= 0x80`) and low-nibble (`< 0x10`) byte values, multi-chunk / multi-file + scaling, and storage/session stability on the Device Under Test (DUT). +* **Interfaces Used**: `gNOI` (`file.File.Put`, `file.File.Stat`, + `file.File.Get`, `file.File.Remove`, `file.File.TransferToRemote`), `gNMI` + (`gNMI.Set`, `gNMI.Get`, `gNMI.Subscribe`). +* **Expected Outcome Summary**: + * Closing a `gnoi.file.File.Put` client stream (`END_STREAM`) without the + mandatory trailing `PutRequest{hash}` message or with a mismatched + `types.HashType` digest returns a clear non-OK gRPC error (for example + `INVALID_ARGUMENT`, `ABORTED`, `FAILED_PRECONDITION`, or `UNKNOWN`) and + removes the incomplete temporary staging file (`File.Stat` returns a + non-OK gRPC error, for example `NOT_FOUND`). + * The DUT's gNOI and gNMI servers remain stable across 50+ sequential + RPCs without AAA/PAM session exhaustion, and existing committed files in + the scratch directory remain unaffected when subsequent negative + `File.Put` streams fail. + * `File.Get` trailing `HashType` digests and any diagnostic hash strings + in error messages are rendered as fixed-length unsigned hex (two + lowercase hex digits per unsigned byte: 64 hex characters for `SHA256` + and 32 hex characters for `MD5`) without `ffffff` signed-char + sign-extension on bytes `>= 0x80` or omitted leading zeros on bytes + `< 0x10`. + * Storage mount-point telemetry + (`/system/mount-points/mount-point/state/size`, `available`, and + `utilized`) is accurately reported via gNMI. + +## Testbed type + +* [`dut.testbed`](https://github.com/openconfig/featureprofiles/blob/main/topologies/dut.testbed) + (`TESTBED_DUT`) + +### Topology + +This test runs on a standalone DUT topology (`TESTBED_DUT`) where the test +client communicates with the DUT's gNMI and gNOI servers over the management / +control-plane transport channel. To ensure dual-stack configuration and +validation coverage, a dedicated non-management test loopback interface (for +example `Loopback10`) is configured with RFC-compliant IPv4 (`192.0.2.1/32`, +RFC 5737) and IPv6 (`2001:db8::1/128`, RFC 3849) addresses, and test file +payloads incorporate both IPv4 and IPv6 control plane records. The in-band +management loopback (for example `Loopback0` / `lo0`) and the DUT's existing +hostname are never changed by this test. On platforms whose loopback naming +only supports index `0`, the test addresses are added to an existing non-zero +subinterface of that loopback instead, without changing the loopback's +interface-level `type`, `description`, or `enabled` settings; if no such +subinterface exists, the test loopback configuration is skipped, since the +gNOI File checks do not depend on it. + +```mermaid +graph LR + Client["Test Client (gNMI / gNOI :9339)"] ===|"gNOI File (Put, Stat, Get, Remove) & gNMI"| DUT["DUT (test loopback: 192.0.2.1/32, 2001:db8::1/128)"] +``` + +## Procedure + +### Test environment setup + +#### Explicit Test Parameters, OC Paths, and Payload Specifications + +* **DUT System Configuration**: + * Read the DUT's current hostname from `/system/state/hostname` (falling + back to `/system/config/hostname`) and re-apply the same value to + `/system/config/hostname`, so the DUT's inventory hostname is preserved. + * Verified state leaf: `/system/state/hostname` equals the re-applied + hostname. + * Verified timestamp leaf: `/system/state/current-datetime` (non-empty) +* **DUT Dual-Stack Test Loopback Interface Configuration (for example + `Loopback10`)**: + * `/interfaces/interface/config/name` = `"Loopback10"` (platform-specific + name of loopback index `10`) + * `/interfaces/interface/config/type` = `"iana-if-type:softwareLoopback"` + * `/interfaces/interface/config/enabled` = `true` + * `/interfaces/interface/config/description` = + `"gNOI File Conformance Test Loopback"` + * `/interfaces/interface/subinterfaces/subinterface/config/index` = `0` + * `/interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/config/ip` + = `"192.0.2.1"` + * `/interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/config/prefix-length` + = `32` + * `/interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/config/ip` + = `"2001:db8::1"` + * `/interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/config/prefix-length` + = `128` +* **Target Scratch Directory (``)**: + * A platform-resolved writable scratch directory on the DUT. Probe the + candidate directories `"/misc/disk1"`, `"harddisk:"`, `"/tmp"` + (default), `"/var/tmp"`, and `"/mnt/flash"` in order with + `gnoi.file.File.Stat` and use the first one that exists; fall back to + `"/tmp"` if none respond. Platform-specific storage paths are probed + before `"/tmp"` because some platforms expose `"/tmp"` to + `File.Stat` but do not accept it as a `File.Put` destination. + * All test file paths below are relative to ``. +* **Storage Mount-Point Telemetry**: + * Verified via `/system/mount-points/mount-point/state/name`, `size`, + `available`, and `utilized`. +* **gNOI RPC Timeout**: + * Every `gnoi.file.File` RPC (each unary call, and each complete client- + or server-streaming exchange) is bounded by a client-side deadline of + `2` minutes. + * A DUT that does not complete an RPC within this deadline fails the + step. A client-side `DEADLINE_EXCEEDED` is never accepted as a valid + rejection for any negative case. + * A `File.Stat` result of `UNAVAILABLE`, `UNIMPLEMENTED`, + `PERMISSION_DENIED`, or `UNAUTHENTICATED` indicates a server or + session failure and is not accepted as a valid file-absent result. +* **Permissions Encoding**: + * Per `gnoi/file/file.proto`, `PutRequest.Details.permissions` and + `StatInfo.permissions` carry the octal permission digits directly in + the `uint32` field with no base conversion (for example, UNIX mode + `0644` is carried as the value `644`, not `420`). +* **Deterministic Payload Definitions**: + * **Payload A (`SHA256` Single-Chunk Baseline)**: + * Target Path: `"/gnoi_conformance_roundtrip_sha256.txt"` + * Permissions: `644` (UNIX mode `0644`) + * ASCII Content (`25` bytes): `"payload-with-wrong-sha256"` + * Hash Method: `types.HashType_SHA256` (`1`) + * Expected 32-Byte Digest (64 lowercase hex chars): + `00d3573788b8879253860be8c1894fbea1a995fc6c5d55cc9be77658b2d72b3b` + (exercises `< 0x10` bytes `0x00` and `0x0b`, and 19 high-bit bytes + `>= 0x80`: `0xd3`, `0x88`, `0xb8`, `0x87`, `0x92`, `0x86`, `0xe8`, + `0xc1`, `0x89`, `0xbe`, `0xa1`, `0xa9`, `0x95`, `0xfc`, `0xcc`, + `0x9b`, `0xe7`, `0xb2`, `0xd7`). + * **Payload B (`MD5` Single-Chunk Baseline)**: + * Target Path: `"/gnoi_conformance_roundtrip_md5.txt"` + * Permissions: `640` (UNIX mode `0640`) + * ASCII Content (`43` bytes): + `"gnoi-conformance-md5-192.0.2.1-2001:db8::1\n"` + * Hash Method: `types.HashType_MD5` (`2`) + * Expected 16-Byte Digest (32 lowercase hex chars): + `5488fc814e0791d457dc8953b529ed7d` (exercises `< 0x10` byte `0x07` + and 9 high-bit bytes `>= 0x80`: `0x88`, `0xfc`, `0x81`, `0x91`, + `0xd4`, `0xdc`, `0x89`, `0xb5`, `0xed`). + * **Payload C (`SHA256` Multi-Chunk `256 KB` Streaming Payload)**: + * Target Path: `"/gnoi_conformance_multichunk_256k.bin"` + * Permissions: `644` (UNIX mode `0644`) + * Content (`262144` bytes = `256 KB`): Constructed by repeating the + 64-byte dual-stack record + `"gnoi-64k-chunk-block-ipv4-192.0.2.1-ipv6-2001:db8::1-padding-01\n"` + exactly `4096` times and transmitted across **4 sequential + `PutRequest{contents}` chunks of `65536` bytes (`64 KB`) each** to + exercise the 64 KB chunk boundary defined in `gnoi/file/file.proto`. + * Hash Method: `types.HashType_SHA256` (`1`) + * Expected 32-Byte Digest (64 lowercase hex chars): + `5437d7315570842dec1cc16a4cc3968538047bdc4a0f640ec5bffe41b3b6881c` + * Expected 16-Byte MD5 Digest (used when the DUT returns an `MD5` + trailing `GetResponse{hash}`; 32 lowercase hex chars): + `b2ac06500bae108061e445f5b6f46751` (exercises `< 0x10` bytes + `0x06`, `0x0b` and high-bit bytes `>= 0x80`: `0xb2`, `0xac`, + `0xae`, `0x80`, `0xe4`, `0xf5`, `0xb6`, `0xf4`). + +#### Setup Execution Steps + +* **Step 1 - Push Baseline DUT Configuration via `gNMI.Set`**: + * Register the deferred cleanup routine (see `Cleanup`) before pushing any + configuration, so the DUT is restored even if setup fails. + * Re-apply the DUT's existing hostname to `/system/config/hostname` using + `gNMI.Set` `REPLACE`. + * Configure the dedicated test loopback with `192.0.2.1/32` and + `2001:db8::1/128` (see `## Canonical OC`) using `gNMI.Set` `UPDATE` + (merge), so no unrelated interface configuration is replaced. +* **Step 2 - Event-Driven State Convergence via `gNMI.Subscribe` + (`ON_CHANGE`) — No Static Sleeps**: + * Do **not** use static sleeps or fixed wait timers. Use `gNMI.Subscribe` + (`ON_CHANGE` mode) with a bounded timeout to confirm configuration and + programming convergence: + 1. Await `/system/state/hostname` equals the re-applied hostname and + verify `/system/state/current-datetime` via `gNMI.Get` is + non-empty. + 2. Await `/interfaces/interface/state/oper-status` == `UP` on the test + loopback (falling back to `/interfaces/interface/state/enabled` == + `true` on platforms that do not stream loopback `oper-status`). + 3. Await + `/interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/state/ip` + == `"192.0.2.1"` (`prefix-length` == `32`) and + `/interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/state/ip` + == `"2001:db8::1"` (`prefix-length` == `128`) on the test loopback + subinterface. + 4. Query `/system/mount-points/mount-point/state/name`, + `/system/mount-points/mount-point/state/size`, + `/system/mount-points/mount-point/state/available`, and + `/system/mount-points/mount-point/state/utilized` via `gNMI.Get` to + record baseline storage capacity, verify `utilized` and `available` + do not exceed `size`, and confirm at least one mount point reports + non-zero `size` and `available`. +* **Step 3 - Pre-Test Scratch File Hygiene**: + * For all test paths + (`/gnoi_conformance_roundtrip_sha256.txt`, + `/gnoi_conformance_roundtrip_md5.txt`, + `/gnoi_conformance_multichunk_256k.bin`, + `/gnoi_conformance_incomplete_no_hash.txt`, + `/gnoi_conformance_hash_mismatch.txt`, and + `/gnoi_conformance_scale_01.txt` through + `/gnoi_conformance_scale_10.txt`), issue + `gnoi.file.File.Remove` (ignoring `NOT_FOUND`) and verify via + `gnoi.file.File.Stat` that each path returns a non-OK gRPC error (for + example `NOT_FOUND`). + +### gNOI-5.4.1 - Positive Single-Chunk and Multi-Chunk gNOI File.Put, File.Stat, and File.Get Baseline with SHA-256 and MD5 Digest Verification + +This subtest establishes the committed baseline files in `` using +both single-chunk and multi-chunk (`4 x 64 KB`) `gnoi.file.File.Put` streams +across `SHA256` and `MD5`, verifies their metadata via `gnoi.file.File.Stat` +and their streamed contents and trailing `types.HashType` digests via +`gnoi.file.File.Get`, and **retains the committed files on disk** so subsequent +subtests (`gNOI-5.4.2` through `gNOI-5.4.5`) build sequentially upon this +state. + +* **Step 1 - Upload Baseline Files via Client-Streaming + `gnoi.file.File.Put`**: + * Open sequential `gnoi.file.File.Put` client streams for Payload A + (`/gnoi_conformance_roundtrip_sha256.txt`, `25` bytes, + permissions `644`, `SHA256`), Payload B + (`/gnoi_conformance_roundtrip_md5.txt`, `43` bytes, + permissions `640`, `MD5`), and Payload C + (`/gnoi_conformance_multichunk_256k.bin`, `262144` bytes + in `4` chunks of `65536` bytes, permissions `644`, `SHA256`). + * For each upload, transmit: + 1. Initial `PutRequest{open}` with `Details.remote_file` and + `Details.permissions`. + 2. One (`Payload A`, `Payload B`) or four (`Payload C`) + `PutRequest{contents}` messages. + 3. Final `PutRequest{hash}` with `types.HashType{method, hash}` set to + the raw 32-byte (`SHA256`) or 16-byte (`MD5`) digest, followed by a + client half-close (`END_STREAM`) and receipt of the RPC response. + * **Validation**: Verify each `gnoi.file.File.Put` call returns + `StatusCode.OK` (`PutResponse{}`). +* **Step 2 - Verify File Metadata via `gnoi.file.File.Stat`**: + * Invoke `gnoi.file.File.Stat` for each of the 3 file paths and for the + parent directory ``. + * **Validation**: + * Verify `StatResponse.stats` contains a `StatInfo` entry whose + `path` matches the target path, `size` equals `25` (Payload A), + `43` (Payload B), and `262144` (Payload C), and `last_modified` is + non-zero. + * Verify `permissions` equals the requested value (`644` or `640`, + octal digits with no base conversion) or, if the DUT applies its + file creation mask, the requested permissions with the reported + `umask` applied (`permissions & ~umask`). `umask` is not required + to be non-zero; a gNOI server running with `umask` `0` legitimately + reports `0`. + * Verify all 3 files appear in the directory `File.Stat` response for + ``. +* **Step 3 - Verify Streamed Payload and Fixed-Length Unsigned Digest via + `gnoi.file.File.Get`**: + * Invoke server-streaming `gnoi.file.File.Get` for each of the 3 baseline + files, reassembling all `GetResponse{contents}` chunks until the final + `GetResponse{hash}` message and the end of the response stream. + * **Validation**: + * Verify the reassembled bytes match the uploaded payload + byte-for-byte (`25`, `43`, and `262144` bytes respectively). + * Verify the trailing `GetResponse{hash}` has `method` equal to + `SHA256` (`32` raw bytes) or `MD5` (`16` raw bytes), and when + rendered as fixed-length lowercase hex produces the exact + 64-character + (`00d3573788b8879253860be8c1894fbea1a995fc6c5d55cc9be77658b2d72b3b` + for Payload A, + `5437d7315570842dec1cc16a4cc3968538047bdc4a0f640ec5bffe41b3b6881c` + for Payload C) or 32-character (`5488fc814e0791d457dc8953b529ed7d` + for Payload B) digest string with no `ffffff` sign-extension on + bytes `>= 0x80` and no dropped leading zero on bytes `< 0x10`. + * **State Retention**: Do **not** remove the 3 baseline files at the end + of `gNOI-5.4.1`; keep them committed in `` for + `gNOI-5.4.2` through `gNOI-5.4.5`. + +### gNOI-5.4.2 - Negative gNOI File.Put Stream Closed Without Trailing HashType Message and Existing-File Preservation + +Building upon the 3 committed baseline files from `gNOI-5.4.1`, this subtest +validates `gnoi/file/file.proto` conformance when a `File.Put` client stream +closes (`END_STREAM`) without sending the mandatory final `PutRequest{hash}` +message, ensuring both a non-OK gRPC error and temporary file cleanup while +confirming existing committed files remain untouched. + +* **Step 1 - Close `gnoi.file.File.Put` Stream Without Trailing `HashType` on + a New Path**: + * Open a client-streaming `gnoi.file.File.Put` RPC for + `"/gnoi_conformance_incomplete_no_hash.txt"`. + * Send `PutRequest{open}` (`remote_file`: + `"/gnoi_conformance_incomplete_no_hash.txt"`, + `permissions`: `644`). + * Send `PutRequest{contents}` with the 53-byte payload + `"incomplete-stream-without-hash-192.0.2.1-2001:db8::1\n"`. + * Immediately half-close the client stream (`END_STREAM`) **without** + sending `PutRequest{hash}`, and wait up to the `2`-minute gNOI RPC + timeout for the RPC to complete. +* **Step 2 - Dual Assertion to Prevent False Positives (RPC Error Status AND + Temporary File Removal)**: + * **Validation (Pass/Fail Criteria)**: + * **Pass**: + 1. The `File.Put` RPC completes within the `2`-minute gNOI RPC + timeout with a non-OK gRPC status code (for example + `INVALID_ARGUMENT`, `ABORTED`, or `FAILED_PRECONDITION`; + `StatusCode.OK` is an immediate test failure). + 2. Subsequent `gnoi.file.File.Stat` and `gnoi.file.File.Get` on + `"/gnoi_conformance_incomplete_no_hash.txt"` both + return a non-OK gRPC error (for example `NOT_FOUND`). + * **Fail**: `File.Put` returns `StatusCode.OK` (`grpc-status: 0`) even + if the temporary file was deleted, the DUT does not terminate the + stream within the `2`-minute gNOI RPC timeout after the client + half-closes it, or `File.Stat` / `File.Get` finds a partial artifact + on disk. +* **Step 3 - Verify Existing Committed Baseline Files from `gNOI-5.4.1` Are + Unaffected**: + * Invoke `gnoi.file.File.Stat` and `gnoi.file.File.Get` on the 3 baseline + files committed in `gNOI-5.4.1` + (`/gnoi_conformance_roundtrip_sha256.txt`, + `/gnoi_conformance_roundtrip_md5.txt`, and + `/gnoi_conformance_multichunk_256k.bin`) and verify their + sizes and trailing `HashType` digests are unchanged. + +### gNOI-5.4.3 - Negative gNOI File.Put Mismatched HashType Digest Rejection and Error Hex Formatting Validation + +Building sequentially on `gNOI-5.4.1` and `gNOI-5.4.2`, this subtest verifies +that supplying a mismatched `SHA256` or `MD5` digest in `PutRequest{hash}` is +rejected with a non-OK gRPC error, removes the staging file, renders any hex +digest in the error message as fixed-length unsigned hex, and leaves the +`gNOI-5.4.1` baseline files intact. + +* **Step 1 - Transmit `gnoi.file.File.Put` with Intentionally Mismatched + `SHA256` Digest**: + * Open a `gnoi.file.File.Put` stream for + `"/gnoi_conformance_hash_mismatch.txt"` (`permissions`: + `644`). + * Send `PutRequest{contents}` with `"payload-with-wrong-sha256"` (`25` + bytes, true SHA-256: + `00d3573788b8879253860be8c1894fbea1a995fc6c5d55cc9be77658b2d72b3b`). + * Send `PutRequest{hash}` with `method: HashType_SHA256` and an all-zero + 32-byte digest (32 bytes of `0x00`), then half-close the stream and + wait for the RPC to complete. +* **Step 2 - Validate Error Status and Unsigned Hex Digest Formatting + (`SHA256`)**: + * **Validation (Pass/Fail Criteria)**: + * **Pass**: + 1. `File.Put` returns a non-OK gRPC status code (for example + `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `ABORTED`, or + `UNKNOWN`). + 2. If any hex digest(s) are included in the gRPC status message + (the client-supplied all-zero digest and/or the computed file + digest), each rendered digest is fixed-length unsigned hex: 64 + hex characters for `SHA256` (32 for `MD5`), with no `ffffff` + signed-char sign-extension (pattern `ffffff[89a-f][0-9a-f]`, + case-insensitive) and no omitted leading zeros. The + client-supplied digest therefore renders as 64 (`SHA256`) or 32 + (`MD5`) `0` characters, and the computed file digest equals + `00d3573788b8879253860be8c1894fbea1a995fc6c5d55cc9be77658b2d72b3b` + (`SHA256`) or `5488fc814e0791d457dc8953b529ed7d` (`MD5`). + 3. `gnoi.file.File.Stat` on + `"/gnoi_conformance_hash_mismatch.txt"` returns a + non-OK gRPC error (for example `NOT_FOUND`). + * **Fail**: `File.Put` returns `StatusCode.OK`, does not complete + within the `2`-minute gNOI RPC timeout, leaves the file on disk, or + renders a digest in the error message with `ffffff` sign-extension, + omitted leading zeros, or the wrong length or value. +* **Step 3 - Transmit `gnoi.file.File.Put` with Intentionally Mismatched + `MD5` Digest and `HashMethod.UNSPECIFIED(0)`**: + * Repeat Steps 1 and 2 for + `"/gnoi_conformance_hash_mismatch.txt"` using Payload B + (`"gnoi-conformance-md5-192.0.2.1-2001:db8::1\n"`) and + `method: HashType_MD5` with an all-zero 16-byte digest (16 bytes of + `0x00`), verifying a non-OK gRPC status, fixed-length 32-character + unsigned hex for any digest in the error message, and a non-OK + `File.Stat` gRPC error (for example `NOT_FOUND`). + * Repeat with `method: HashType_UNSPECIFIED` (`0`), verifying a non-OK + gRPC status and a non-OK `File.Stat` gRPC error (for example + `NOT_FOUND`). +* **Step 4 - Confirm `gNOI-5.4.1` Baseline Files Remain Intact**: + * Verify via `gnoi.file.File.Stat` that all 3 baseline files from + `gNOI-5.4.1` remain present with their exact byte sizes. + +### gNOI-5.4.4 - Modest Scale: Multi-File Batch Staging (10 Files), Directory File.Stat, and Mount-Point Telemetry + +Building on the 3 committed files from `gNOI-5.4.1`, this subtest adds modest +scale by staging 10 additional files (`5` `SHA256` and `5` `MD5`, for `13` +concurrent test files in `` and `50+` cumulative gNOI RPC +invocations) to validate directory-level `File.Stat`, gNMI storage mount-point +telemetry, and gNOI AAA session stability. + +* **Step 1 - Stage 10 Additional Files Across `SHA256` and `MD5`**: + * For index `i` from `1` to `10`, upload + `/gnoi_conformance_scale_NN.txt` (where `NN` is `i` + zero-padded to two decimal digits, `01` through `10`; `permissions`: + `644`) with the deterministic dual-stack ASCII payload + `gnoi-scale-file-NN-ipv4-198.51.100.-ipv6-2001:db8:100::` + followed by a newline, where `` is `i` in decimal and `` is `i` + in lowercase hexadecimal (for example, `i` = `10` produces + `"gnoi-scale-file-10-ipv4-198.51.100.10-ipv6-2001:db8:100::a\n"`). + * Use `HashType_SHA256` for odd `i` (`1, 3, 5, 7, 9`) and `HashType_MD5` + for even `i` (`2, 4, 6, 8, 10`). + * Verify each `gnoi.file.File.Put` returns `StatusCode.OK`. +* **Step 2 - Verify Directory-Level `gnoi.file.File.Stat` and Streamed + `gnoi.file.File.Get`**: + * Invoke `gnoi.file.File.Stat` on `` and verify that all + `13` committed files (`3` from `gNOI-5.4.1` + `10` from `gNOI-5.4.4`) + are present in `StatResponse.stats` with exact byte sizes. + * Invoke `gnoi.file.File.Get` on each of the 10 scale files and verify + payload equality and exact 64-char (`SHA256`) or 32-char (`MD5`) + trailing `HashType` digests. +* **Step 3 - Verify Storage Mount-Point Telemetry via `gNMI.Subscribe`**: + * Use `gNMI.Subscribe` on + `/system/mount-points/mount-point/state/name`, + `/system/mount-points/mount-point/state/size`, + `/system/mount-points/mount-point/state/available`, and + `/system/mount-points/mount-point/state/utilized` to confirm storage + accounting remains valid and responsive without gNOI/gNMI session errors + (`UNAVAILABLE` or `RESOURCE_EXHAUSTED`). + +### gNOI-5.4.5 - Protocol-Level Mandatory Negative Cases and Final File.Remove Verification + +This subtest executes additional mandatory negative protocol checks on the +`gnoi.file.File` service and then removes all `13` committed files created in +`gNOI-5.4.1` and `gNOI-5.4.4`. + +* **Step 1 - Negative Case: Protocol Sequence Violation + (`PutRequest{contents}` Sent Before `PutRequest{open}`)**: + * Open a `gnoi.file.File.Put` stream and immediately send a + `PutRequest{contents}` message carrying the ASCII bytes + `"contents-before-open"` as the first message, without sending an + initial `PutRequest{open}` message, then half-close the stream and wait + for the RPC to complete. + * **Validation**: Verify `File.Put` returns a non-OK gRPC error (for + example `INVALID_ARGUMENT` or `FAILED_PRECONDITION`). +* **Step 2 - Negative Case: Invalid `remote_file` in `PutRequest{open}`**: + * Per `gnoi/file/file.proto` (*"The remote_file must be an absolute + path"*), open a separate `gnoi.file.File.Put` stream for each of the + following `remote_file` values: an empty path (`""`), a relative path + (`"relative/path/gnoi_invalid_dir.txt"`), and an existing directory + path (``). For each stream, send `PutRequest{open}` + (`permissions`: `644`), `PutRequest{contents}` with Payload A, and the + valid Payload A `PutRequest{hash}`, then half-close the stream and wait + for the RPC to complete. + * A non-existent parent directory is intentionally **not** used as a + negative case, because `gnoi/file/file.proto` states *"If the path to + remote_file doesn't exist it will be created"*, so such an upload can + legitimately succeed on a compliant DUT. + * **Validation**: Verify each `File.Put` returns a non-OK gRPC error (for + example `INVALID_ARGUMENT` or `FAILED_PRECONDITION`), and that + `gnoi.file.File.Stat` on `` still succeeds afterwards + (the existing directory is not replaced). +* **Step 3 - Negative Case: `File.Stat`, `File.Get`, `File.Remove`, and + `File.TransferToRemote` on Non-Existent, Empty, Relative, and Directory + Paths**: + * Invoke `gnoi.file.File.Stat` with an empty path (`""`) and a relative + path (`"relative/path/gnoi_conformance_file.txt"`), verifying both + return a non-OK gRPC error (for example `INVALID_ARGUMENT` or + `NOT_FOUND`). + * Invoke `gnoi.file.File.Get` on + `"/gnoi_conformance_nonexistent_file.txt"`, an empty path + (`""`), and a relative path + (`"relative/path/gnoi_conformance_file.txt"`), verifying each returns a + non-OK gRPC error (for example `NOT_FOUND` or `INVALID_ARGUMENT`). + * Invoke `gnoi.file.File.Remove` on + `"/gnoi_conformance_nonexistent_file.txt"`, an empty path + (`""`), and the scratch directory itself (``), verifying + each returns a non-OK gRPC error per `gnoi/file/file.proto` (*"An error + is returned if the file does not exist, is a directory, or the remove + operation encounters an error"*), and that `gnoi.file.File.Stat` on + `` still succeeds afterwards. + * Invoke `gnoi.file.File.TransferToRemote` with an empty + `TransferToRemoteRequest{}` and with `local_path` set without + `remote_download`, verifying both return a non-OK gRPC error (for + example `INVALID_ARGUMENT`, `NOT_FOUND`, or `UNIMPLEMENTED`). +* **Step 4 - Final `gnoi.file.File.Remove` Verification Across All 13 + Committed Files**: + * Invoke `gnoi.file.File.Remove` for all `3` baseline files from + `gNOI-5.4.1` and all `10` scale files from `gNOI-5.4.4`, verifying each + returns `StatusCode.OK`. + * Invoke `gnoi.file.File.Stat` for each of the `13` paths and verify each + returns a non-OK gRPC error (for example `NOT_FOUND`). + +### Cleanup + +* Before any configuration is pushed, arrange a cleanup procedure that always + runs when the test completes (whether it passes or fails) and that: + 1. Invokes `gnoi.file.File.Remove` (`RemoveRequest{remote_file}`) for all + `15` test file paths + (`/gnoi_conformance_roundtrip_sha256.txt`, + `/gnoi_conformance_roundtrip_md5.txt`, + `/gnoi_conformance_multichunk_256k.bin`, + `/gnoi_conformance_incomplete_no_hash.txt`, + `/gnoi_conformance_hash_mismatch.txt`, and + `/gnoi_conformance_scale_01.txt` through + `/gnoi_conformance_scale_10.txt`), ignoring `NOT_FOUND` + errors, so no temporary files remain on the DUT regardless of test + outcome. + 2. Reverts test-specific DUT configuration via `gNMI.Set` to restore the + DUT to its exact pre-test baseline state: + * If the dedicated test loopback existed before the test, its + original configuration is restored; otherwise the test loopback + (and its default network-instance binding, where required) is + deleted. + * On platforms where the test reuses an existing loopback + subinterface, the original subinterface configuration is restored, + or only the test IPv4/IPv6 addresses are removed. + * The DUT's original hostname is re-applied. + 3. Uses `gNMI.Subscribe` / `gNMI.Get` on `/system/state/current-datetime` + and `/system/mount-points/mount-point/state/available` to confirm the + DUT management plane and storage mount points remain healthy after test + completion. + +## Canonical OC + +```json +{ + "interfaces": { + "interface": [ + { + "config": { + "description": "gNOI File Conformance Test Loopback", + "enabled": true, + "name": "Loopback10", + "type": "iana-if-type:softwareLoopback" + }, + "name": "Loopback10", + "subinterfaces": { + "subinterface": [ + { + "config": { + "index": 0 + }, + "index": 0, + "ipv4": { + "addresses": { + "address": [ + { + "config": { + "ip": "192.0.2.1", + "prefix-length": 32 + }, + "ip": "192.0.2.1" + } + ] + } + }, + "ipv6": { + "addresses": { + "address": [ + { + "config": { + "ip": "2001:db8::1", + "prefix-length": 128 + }, + "ip": "2001:db8::1" + } + ] + } + } + } + ] + } + } + ] + } +} +``` + +## OpenConfig Path and RPC Coverage + +The below yaml defines the OC paths and gNOI/gNMI RPCs intended to be covered by +this test. + +```yaml +paths: + # System and storage mount-point state verification + /system/config/hostname: + /system/state/hostname: + /system/state/current-datetime: + /system/mount-points/mount-point/state/name: + /system/mount-points/mount-point/state/size: + /system/mount-points/mount-point/state/available: + /system/mount-points/mount-point/state/utilized: + + # Dual-stack loopback interface configuration and state + /interfaces/interface/config/description: + /interfaces/interface/config/enabled: + /interfaces/interface/config/name: + /interfaces/interface/config/type: + /interfaces/interface/state/enabled: + /interfaces/interface/state/oper-status: + /interfaces/interface/subinterfaces/subinterface/config/index: + /interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/config/ip: + /interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/config/prefix-length: + /interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/state/ip: + /interfaces/interface/subinterfaces/subinterface/ipv4/addresses/address/state/prefix-length: + /interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/config/ip: + /interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/config/prefix-length: + /interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/state/ip: + /interfaces/interface/subinterfaces/subinterface/ipv6/addresses/address/state/prefix-length: + +rpcs: + gnmi: + gNMI.Get: + gNMI.Set: + gNMI.Subscribe: + on_change: true + gnoi: + file.File.Get: + file.File.Put: + file.File.Remove: + file.File.Stat: + file.File.TransferToRemote: +``` + +## Required DUT platform + +* FFF +* MFF diff --git a/feature/gnoi/system/tests/gnoi_file_conformance_test/gnoi_file_conformance_test.go b/feature/gnoi/system/tests/gnoi_file_conformance_test/gnoi_file_conformance_test.go new file mode 100644 index 00000000000..05b63299485 --- /dev/null +++ b/feature/gnoi/system/tests/gnoi_file_conformance_test/gnoi_file_conformance_test.go @@ -0,0 +1,1223 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package gnoi_file_conformance_test implements gNOI-5.4: gNOI File Put and +// Stat Protocol Conformance. +package gnoi_file_conformance_test + +import ( + "bytes" + "context" + "crypto/sha256" + "crypto/sha512" + "encoding/hex" + "errors" + "fmt" + "io" + "path" + "regexp" + "strconv" + "strings" + "testing" + "time" + + "github.com/openconfig/featureprofiles/internal/deviations" + "github.com/openconfig/featureprofiles/internal/fptest" + fpb "github.com/openconfig/gnoi/file" + tpb "github.com/openconfig/gnoi/types" + "github.com/openconfig/ondatra" + "github.com/openconfig/ondatra/gnmi" + "github.com/openconfig/ondatra/gnmi/oc" + "github.com/openconfig/ondatra/netutil" + "github.com/openconfig/ygnmi/ygnmi" + "github.com/openconfig/ygot/ygot" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) + +const ( + dutHostname = "dut" + loopbackDesc = "gNOI File Conformance Test Loopback" + defaultLoopbackIndex = 0 + testLoopbackIndex = 10 + loopbackSubintf = uint32(0) + loopbackIPv4 = "192.0.2.1" + loopbackIPv4PLen = uint8(32) + loopbackIPv6 = "2001:db8::1" + loopbackIPv6PLen = uint8(128) + watchTimeout = 2 * time.Minute + // rpcTimeout bounds each gnoi.file.File RPC (unary call or complete + // stream) so that a DUT that never responds fails the step instead of + // hanging the test. + rpcTimeout = 2 * time.Minute + + defaultScratchDir = "/tmp" + chunkSize64KB = 64 * 1024 // 65536 bytes + multiChunkCount = 4 + multiChunkTotal = chunkSize64KB * multiChunkCount // 262144 bytes (256 KB) + scaleFileCount = 10 + + // Explicit deterministic payloads and precomputed hex digests defined in + // the gNOI-5.4 README. Permissions carry the octal digits directly in the + // uint32 field with no base conversion, per gnoi/file/file.proto (e.g. UNIX + // mode 0644 is sent as the value 644). + payloadAContent = "payload-with-wrong-sha256" + payloadASHA256Hex = "00d3573788b8879253860be8c1894fbea1a995fc6c5d55cc9be77658b2d72b3b" + payloadAPerms = uint32(644) + + payloadBContent = "gnoi-conformance-md5-192.0.2.1-2001:db8::1\n" + payloadBMD5Hex = "5488fc814e0791d457dc8953b529ed7d" + payloadBPerms = uint32(640) + + payloadCRecord = "gnoi-64k-chunk-block-ipv4-192.0.2.1-ipv6-2001:db8::1-padding-01\n" + payloadCRecordCount = 4096 // 64 bytes * 4096 = 262144 bytes (256 KB) + payloadCSHA256Hex = "5437d7315570842dec1cc16a4cc3968538047bdc4a0f640ec5bffe41b3b6881c" + // payloadCMD5Hex is the RFC 1321 MD5 digest of Payload C, used when the DUT + // returns an MD5 trailing GetResponse{hash} for the multi-chunk file. + payloadCMD5Hex = "b2ac06500bae108061e445f5b6f46751" + payloadCPerms = uint32(644) + + incompleteNoHashPayload = "incomplete-stream-without-hash-192.0.2.1-2001:db8::1\n" + contentsBeforeOpenData = "contents-before-open" + + fileNameRoundtripSHA256 = "gnoi_conformance_roundtrip_sha256.txt" + fileNameRoundtripMD5 = "gnoi_conformance_roundtrip_md5.txt" + fileNameMultiChunk256K = "gnoi_conformance_multichunk_256k.bin" + fileNameIncompleteNoHash = "gnoi_conformance_incomplete_no_hash.txt" + fileNameHashMismatch = "gnoi_conformance_hash_mismatch.txt" + fileNameNonExistent = "gnoi_conformance_nonexistent_file.txt" + relativePutFilePath = "relative/path/gnoi_invalid_dir.txt" + relativeTestFilePath = "relative/path/gnoi_conformance_file.txt" +) + +// signExtensionHexPattern matches signed-char sign-extension corruption +// (e.g., ffffffd3 or ffffff88) on digest bytes >= 0x80 when formatted with %x. +var signExtensionHexPattern = regexp.MustCompile(`(?i)ffffff[89a-f][0-9a-f]`) + +// errorDigestHexPattern captures a hex digest rendered in an error message +// immediately after a digest label (e.g. "File hash: 00d357..."), so its length +// and value can be compared against the expected fixed-length %02x encoding. +var errorDigestHexPattern = regexp.MustCompile(`(?i)\b(?:hash|digest|checksum)\b\W{1,3}([0-9a-f]{8,})\b`) + +func TestMain(m *testing.M) { + fptest.RunTests(m) +} + +// fileSpec describes a deterministic test file to be staged and verified via +// the gNOI File service. +type fileSpec struct { + name string + path string + perms uint32 + payload []byte + chunkSize int + hashMethod tpb.HashType_HashMethod + wantDigest []byte + wantHex string +} + +// md5TestVectors stores precomputed RFC 1321 MD5 hex digests for the +// deterministic gNOI-5.4 test payloads, avoiding both custom MD5 +// implementations and the nogo-disallowed crypto/md5 package. +var md5TestVectors = map[string]string{ + payloadAContent: "685b384280d8ecffa4afc295b5d2613b", + payloadBContent: payloadBMD5Hex, + "gnoi-scale-file-01-ipv4-198.51.100.1-ipv6-2001:db8:100::1\n": "410725f4f7f53848b689ef69885ebee4", + "gnoi-scale-file-02-ipv4-198.51.100.2-ipv6-2001:db8:100::2\n": "bde5e04c82656916b9f1602b66868f85", + "gnoi-scale-file-03-ipv4-198.51.100.3-ipv6-2001:db8:100::3\n": "7f3e74642b3ddcaec3db3d6a6006d796", + "gnoi-scale-file-04-ipv4-198.51.100.4-ipv6-2001:db8:100::4\n": "b541a6dc6c980aeb5038e40c64ab0842", + "gnoi-scale-file-05-ipv4-198.51.100.5-ipv6-2001:db8:100::5\n": "cfe46608ad0d089026445e04e09fc986", + "gnoi-scale-file-06-ipv4-198.51.100.6-ipv6-2001:db8:100::6\n": "c70b1bcc67b04f20a180f74c2b373391", + "gnoi-scale-file-07-ipv4-198.51.100.7-ipv6-2001:db8:100::7\n": "535c9f9be8f293dffa46293e4a4f530b", + "gnoi-scale-file-08-ipv4-198.51.100.8-ipv6-2001:db8:100::8\n": "8aafe8f752a02b4c214e4338b29259b0", + "gnoi-scale-file-09-ipv4-198.51.100.9-ipv6-2001:db8:100::9\n": "685ffa473ed90e8701134cc5ddfad22e", + "gnoi-scale-file-10-ipv4-198.51.100.10-ipv6-2001:db8:100::a\n": "6084d4c6b5751517cd1868f8c015fd4e", +} + +// init registers the Payload C MD5 test vector, whose 256 KB payload cannot be +// written as a map literal key. +func init() { + md5TestVectors[strings.Repeat(payloadCRecord, payloadCRecordCount)] = payloadCMD5Hex +} + +// computeDigest computes the raw digest bytes and lowercase 2-digit hex string +// for the given payload and gNOI HashMethod. +func computeDigest(t *testing.T, payload []byte, method tpb.HashType_HashMethod) ([]byte, string) { + t.Helper() + switch method { + case tpb.HashType_SHA256: + sum := sha256.Sum256(payload) + raw := sum[:] + return raw, hex.EncodeToString(raw) + case tpb.HashType_SHA512: + sum := sha512.Sum512(payload) + raw := sum[:] + return raw, hex.EncodeToString(raw) + case tpb.HashType_MD5: + md5Hex, ok := md5TestVectors[string(payload)] + if !ok { + t.Fatalf("Missing precomputed RFC 1321 MD5 test vector for payload %q", string(payload)) + } + raw, err := hex.DecodeString(md5Hex) + if err != nil { + t.Fatalf("hex.DecodeString(%q) failed: %v", md5Hex, err) + } + return raw, md5Hex + default: + t.Fatalf("Unsupported HashMethod: %v", method) + return nil, "" + } +} + +// rpcContext returns a context bounded by rpcTimeout for a single +// gnoi.file.File RPC. The context is cancelled when the calling (sub)test +// completes. +func rpcContext(ctx context.Context, t *testing.T) context.Context { + t.Helper() + rctx, cancel := context.WithTimeout(ctx, rpcTimeout) + t.Cleanup(cancel) + return rctx +} + +// isRPCTimeout reports whether err is the client-side rpcTimeout expiring, +// meaning the DUT never completed the RPC. Such an error is never accepted as +// a valid rejection for a negative case. +func isRPCTimeout(err error) bool { + return errors.Is(err, context.DeadlineExceeded) || status.Code(err) == codes.DeadlineExceeded +} + +// resolveScratchDir determines the writable scratch directory on the DUT using +// gNOI File.Stat without calling dut.Vendor(). Platform-specific storage paths +// are probed before "/tmp" because some platforms expose "/tmp" to File.Stat +// but reject it as a File.Put destination. Defaults to "/tmp" as specified in +// the README. +func resolveScratchDir(ctx context.Context, t *testing.T, fc fpb.FileClient) string { + t.Helper() + candidates := []string{"/misc/disk1", "harddisk:", defaultScratchDir, "/var/tmp", "/mnt/flash"} + for _, dir := range candidates { + _, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: dir}) + if err == nil { + t.Logf("Resolved writable scratch directory via gNOI File.Stat: %s", dir) + return dir + } + t.Logf("gNOI File.Stat(%q) probe returned: %v", dir, err) + } + t.Logf("Falling back to default scratch directory: %s", defaultScratchDir) + return defaultScratchDir +} + +// allTestFilePaths returns the full list of 15 test file paths used across +// gNOI-5.4.1 through gNOI-5.4.5 for pre-test hygiene and deferred cleanup. +func allTestFilePaths(scratchDir string) []string { + paths := []string{ + path.Join(scratchDir, fileNameRoundtripSHA256), + path.Join(scratchDir, fileNameRoundtripMD5), + path.Join(scratchDir, fileNameMultiChunk256K), + path.Join(scratchDir, fileNameIncompleteNoHash), + path.Join(scratchDir, fileNameHashMismatch), + } + for i := 1; i <= scaleFileCount; i++ { + paths = append(paths, path.Join(scratchDir, fmt.Sprintf("gnoi_conformance_scale_%02d.txt", i))) + } + return paths +} + +// resolveTestLoopback returns a non-management loopback interface name and +// subinterface index on the DUT, and whether a test loopback should be +// configured. When cli_takes_precedence_over_oc is enabled (e.g. Juniper, where +// entity-naming only supports loopback index 0 and only one loopback unit is +// permitted per routing instance), it reuses an active non-zero subinterface on +// lo0 via gnmi.Update without replacing the subinterface; if no such +// subinterface exists, the test loopback configuration is skipped, since the +// gNOI File checks do not depend on it. Otherwise it selects a dedicated +// non-zero loopback interface (index 10, e.g. Loopback10 / lo10) so +// Loopback0 / lo0 in-band management is never modified. +func resolveTestLoopback(t *testing.T, dut *ondatra.DUTDevice) (string, uint32, bool) { + t.Helper() + if !deviations.CLITakesPrecedenceOverOC(dut) { + return netutil.LoopbackInterface(t, dut, testLoopbackIndex), loopbackSubintf, true + } + lbIntfName := netutil.LoopbackInterface(t, dut, defaultLoopbackIndex) + for _, subVal := range gnmi.LookupAll(t, dut, gnmi.OC().Interface(lbIntfName).SubinterfaceAny().Index().State()) { + if idx, ok := subVal.Val(); ok && idx > 0 { + t.Logf("Resolved active master loopback subinterface on %s: index=%d", lbIntfName, idx) + return lbIntfName, idx, true + } + } + t.Logf("No active non-zero subinterface on %s; skipping test loopback configuration (an additional loopback unit cannot be created on this platform)", lbIntfName) + return lbIntfName, 0, false +} + +// configureLoopbackInterface pushes the dual-stack loopback configuration on +// lbIntfName at subinterface lbSubIdx using gnmi.Update (never gnmi.Replace on +// Loopback0) so in-band management interfaces are never disrupted. Interface- +// level leaves (description, type, enabled) are set only on the dedicated test +// loopback; when an existing loopback is reused (cli_takes_precedence_over_oc), +// only the test addresses are added so cleanup fully restores the baseline. +func configureLoopbackInterface(t *testing.T, dut *ondatra.DUTDevice, lbIntfName string, lbSubIdx uint32) { + t.Helper() + loIntf := &oc.Interface{ + Name: ygot.String(lbIntfName), + } + if !deviations.CLITakesPrecedenceOverOC(dut) { + loIntf.Description = ygot.String(loopbackDesc) + loIntf.Type = oc.IETFInterfaces_InterfaceType_softwareLoopback + if deviations.InterfaceEnabled(dut) { + loIntf.Enabled = ygot.Bool(true) + } + } + sub := loIntf.GetOrCreateSubinterface(lbSubIdx) + v4 := sub.GetOrCreateIpv4() + if deviations.InterfaceEnabled(dut) && !deviations.IPv4MissingEnabled(dut) { + v4.Enabled = ygot.Bool(true) + } + v4.GetOrCreateAddress(loopbackIPv4).PrefixLength = ygot.Uint8(loopbackIPv4PLen) + + v6 := sub.GetOrCreateIpv6() + if deviations.InterfaceEnabled(dut) { + v6.Enabled = ygot.Bool(true) + } + v6.GetOrCreateAddress(loopbackIPv6).PrefixLength = ygot.Uint8(loopbackIPv6PLen) + + fptest.LogQuery(t, "DUT loopback interface config", gnmi.OC().Interface(lbIntfName).Config(), loIntf) + gnmi.Update(t, dut, gnmi.OC().Interface(lbIntfName).Config(), loIntf) + if deviations.ExplicitInterfaceInDefaultVRF(dut) { + fptest.AssignToNetworkInstance(t, dut, lbIntfName, deviations.DefaultNetworkInstance(dut), lbSubIdx) + } +} + +// resolveTargetHostname returns the DUT's existing operational or configured +// hostname so exercising /system/config/hostname via gNMI.Set preserves the +// device's real inventory hostname (preventing serial console prompt mismatches +// during lab device recovery). +func resolveTargetHostname(t *testing.T, dut *ondatra.DUTDevice) string { + t.Helper() + if stateHost, ok := gnmi.Lookup(t, dut, gnmi.OC().System().Hostname().State()).Val(); ok && stateHost != "" { + return stateHost + } + if cfgHost, ok := gnmi.LookupConfig(t, dut, gnmi.OC().System().Hostname().Config()).Val(); ok && cfgHost != "" { + return cfgHost + } + return dutHostname +} + +// revertLoopback restores the pre-test loopback configuration on the DUT +// without ever replacing or deleting Loopback0 / lo0. The dedicated test +// loopback interface is restored to its original configuration if it existed +// before the test, and deleted only if it was created by the test. +func revertLoopback(t *testing.T, dut *ondatra.DUTDevice, lbIntfName string, lbSubIdx uint32, origLoIntf *ygnmi.Value[*oc.Interface], origLoSub *ygnmi.Value[*oc.Interface_Subinterface]) { + t.Helper() + prevSub, subExisted := origLoSub.Val() + subExisted = subExisted && prevSub != nil + if deviations.CLITakesPrecedenceOverOC(dut) { + if subExisted { + gnmi.Replace(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Config(), prevSub) + } else { + gnmi.Delete(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv4().Address(loopbackIPv4).Config()) + gnmi.Delete(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv6().Address(loopbackIPv6).Config()) + } + return + } + if deviations.ExplicitInterfaceInDefaultVRF(dut) && !subExisted { + gnmi.Delete(t, dut, gnmi.OC().NetworkInstance(deviations.DefaultNetworkInstance(dut)).Interface(fmt.Sprintf("%s.%d", lbIntfName, lbSubIdx)).Config()) + } + if prevIntf, ok := origLoIntf.Val(); ok && prevIntf != nil { + gnmi.Replace(t, dut, gnmi.OC().Interface(lbIntfName).Config(), prevIntf) + } else { + gnmi.Delete(t, dut, gnmi.OC().Interface(lbIntfName).Config()) + } +} + +// awaitEnvironmentConvergence verifies hostname and current-datetime state +// convergence via gNMI. +func awaitEnvironmentConvergence(t *testing.T, dut *ondatra.DUTDevice, targetHostname string) { + t.Helper() + if deviations.CLITakesPrecedenceOverOC(dut) { + if gotHost := gnmi.Get(t, dut, gnmi.OC().System().Hostname().Config()); gotHost != targetHostname { + t.Fatalf("Config hostname mismatch: got %q, want %q", gotHost, targetHostname) + } + } else { + gnmi.Await(t, dut, gnmi.OC().System().Hostname().State(), watchTimeout, targetHostname) + } + + if _, ok := gnmi.Watch(t, dut, gnmi.OC().System().CurrentDatetime().State(), watchTimeout, func(val *ygnmi.Value[string]) bool { + v, present := val.Val() + return present && v != "" + }).Await(t); !ok { + t.Fatalf("Timed out waiting for non-empty /system/state/current-datetime") + } +} + +// awaitLoopbackConvergence verifies test loopback oper-status (or enabled) and +// dual-stack address state convergence via gNMI. +func awaitLoopbackConvergence(t *testing.T, dut *ondatra.DUTDevice, lbIntfName string, lbSubIdx uint32) { + t.Helper() + if _, ok := gnmi.Watch(t, dut, gnmi.OC().Interface(lbIntfName).OperStatus().State(), watchTimeout, func(val *ygnmi.Value[oc.E_Interface_OperStatus]) bool { + v, present := val.Val() + return present && v == oc.Interface_OperStatus_UP + }).Await(t); !ok { + t.Logf("Interface %s did not stream oper-status within %v; verifying /interfaces/interface[name=%s]/state/enabled is true", lbIntfName, watchTimeout, lbIntfName) + gnmi.Await(t, dut, gnmi.OC().Interface(lbIntfName).Enabled().State(), watchTimeout, true) + } + gnmi.Await(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv4().Address(loopbackIPv4).Ip().State(), watchTimeout, loopbackIPv4) + gnmi.Await(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv4().Address(loopbackIPv4).PrefixLength().State(), watchTimeout, loopbackIPv4PLen) + gnmi.Await(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv6().Address(loopbackIPv6).Ip().State(), watchTimeout, loopbackIPv6) + gnmi.Await(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Ipv6().Address(loopbackIPv6).PrefixLength().State(), watchTimeout, loopbackIPv6PLen) +} + +// setupEnvironment implements the "Test environment setup" section of the +// gNOI-5.4 README: +// - Step 1: Register t.Cleanup first, then push baseline DUT configuration +// (hostname + dual-stack loopback) via gNMI.Set. +// - Step 2: Event-driven state convergence via gnmi.Watch / gnmi.Await (no +// static time.Sleep) for /system/state/hostname, /system/state/current-datetime, +// loopback oper-status, dual-stack IPv4/IPv6 addresses, and +// /system/mount-points/mount-point/state/* telemetry. +// - Step 3: Pre-test scratch file hygiene via gnoi.file.File.Remove and +// verification of NOT_FOUND via gnoi.file.File.Stat. +func setupEnvironment(ctx context.Context, t *testing.T, dut *ondatra.DUTDevice, fc fpb.FileClient, filesRemoved *bool) string { + t.Helper() + t.Log("Test environment setup - Step 1: Configure baseline DUT hostname and dual-stack loopback interface via gNMI.Set") + + targetHostname := resolveTargetHostname(t, dut) + lbIntfName, lbSubIdx, lbConfigured := resolveTestLoopback(t, dut) + var origLoIntf *ygnmi.Value[*oc.Interface] + var origLoSub *ygnmi.Value[*oc.Interface_Subinterface] + if lbConfigured { + origLoIntf = gnmi.LookupConfig(t, dut, gnmi.OC().Interface(lbIntfName).Config()) + origLoSub = gnmi.LookupConfig(t, dut, gnmi.OC().Interface(lbIntfName).Subinterface(lbSubIdx).Config()) + } + scratchDir := resolveScratchDir(ctx, t, fc) + cleanupPaths := allTestFilePaths(scratchDir) + + // Register deferred Cleanup BEFORE pushing any gNMI config so cleanup runs + // even if setup fails mid-way. + t.Cleanup(func() { + if !*filesRemoved { + t.Log("Cleanup - Step 1: Removing all 15 gNOI conformance test files via gnoi.file.File.Remove") + for _, p := range cleanupPaths { + rmCtx, cancel := context.WithTimeout(ctx, rpcTimeout) + _, _ = fc.Remove(rmCtx, &fpb.RemoveRequest{RemoteFile: p}) + cancel() + } + } + + t.Log("Cleanup - Step 2: Reverting DUT loopback interface and hostname configuration to pre-test baseline") + if lbConfigured { + revertLoopback(t, dut, lbIntfName, lbSubIdx, origLoIntf, origLoSub) + } + if targetHostname != "" { + gnmi.Replace(t, dut, gnmi.OC().System().Hostname().Config(), targetHostname) + } + + t.Log("Cleanup - Step 3: Verifying DUT management plane and storage mount points remain healthy") + if _, ok := gnmi.Watch(t, dut, gnmi.OC().System().CurrentDatetime().State(), watchTimeout, func(val *ygnmi.Value[string]) bool { + v, present := val.Val() + return present && v != "" + }).Await(t); !ok { + t.Errorf("Cleanup: /system/state/current-datetime did not report a valid timestamp") + } + verifyMountPointsTelemetry(t, dut) + }) + + fptest.ConfigureDefaultNetworkInstance(t, dut) + gnmi.Replace(t, dut, gnmi.OC().System().Hostname().Config(), targetHostname) + if lbConfigured { + configureLoopbackInterface(t, dut, lbIntfName, lbSubIdx) + } + + t.Log("Test environment setup - Step 2: Event-driven state convergence via gnmi.Watch (gNMI.Subscribe ON_CHANGE)") + awaitEnvironmentConvergence(t, dut, targetHostname) + if lbConfigured { + awaitLoopbackConvergence(t, dut, lbIntfName, lbSubIdx) + } + verifyMountPointsTelemetry(t, dut) + + t.Log("Test environment setup - Step 3: Pre-test scratch file hygiene via gnoi.file.File.Remove and File.Stat") + for _, p := range cleanupPaths { + _, err := fc.Remove(rpcContext(ctx, t), &fpb.RemoveRequest{RemoteFile: p}) + if err != nil && status.Code(err) != codes.NotFound && status.Code(err) != codes.Unknown { + t.Logf("Pre-test Remove(%q) returned non-fatal status %v: %v", p, status.Code(err), err) + } + verifyFileStatNotFound(ctx, t, fc, p) + } + + return scratchDir +} + +// validateMountPoint checks a single mount-point state entry and returns true +// if it reports writable scratch capacity. +func validateMountPoint(t *testing.T, mp *oc.System_MountPoint) bool { + t.Helper() + mpName := mp.GetName() + if mpName == "" { + t.Errorf("Mount point reported empty /system/mount-points/mount-point/state/name") + return false + } + // Virtual, read-only, or ephemeral mount points (for example /proc, /dev, + // or /run/user/*) may not report capacity leaves, so skip them here; + // verifyMountPointsTelemetry still requires at least one mount point with + // non-zero size and available capacity. + if mp.Size == nil || mp.Available == nil || mp.Utilized == nil { + t.Logf("Skipping mount point %q because one or more capacity leaves (size=%v, available=%v, utilized=%v) are unpopulated", mpName, mp.Size != nil, mp.Available != nil, mp.Utilized != nil) + return false + } + size := mp.GetSize() + available := mp.GetAvailable() + utilized := mp.GetUtilized() + + t.Logf("Mount point %q telemetry: size=%d, available=%d, utilized=%d", mpName, size, available, utilized) + if utilized > size { + t.Errorf("Mount point %q utilized (%d) > size (%d)", mpName, utilized, size) + } + if available > size { + t.Errorf("Mount point %q available (%d) > size (%d)", mpName, available, size) + } + return size > 0 && available > 0 +} + +// verifyMountPointsTelemetry validates /system/mount-points/mount-point/state +// leaves (name, size, available, utilized), using leaf queries when a +// functional translator is active (since ygnmi functional translators only +// support leaf paths) and a single container gnmi.GetAll query otherwise. +func verifyMountPointsTelemetry(t *testing.T, dut *ondatra.DUTDevice) { + t.Helper() + ftName := deviations.SystemMountPointStateFt(dut) + opts := fptest.GetOptsForFunctionalTranslator(t, ftName) + gnmiOpts := dut.GNMIOpts().WithYGNMIOpts(opts...) + + var mountPoints []*oc.System_MountPoint + if ftName != "" { + // Functional translators only support single-leaf queries, so query each + // leaf with a wildcard mount-point key and join the results by name. + mpNames := gnmi.GetAll(t, gnmiOpts, gnmi.OC().System().MountPointAny().Name().State()) + if len(mpNames) == 0 { + t.Fatalf("No storage mount points reported under /system/mount-points/mount-point/state") + } + sizes := mountPointLeafValues(t, gnmiOpts, gnmi.OC().System().MountPointAny().Size().State()) + availables := mountPointLeafValues(t, gnmiOpts, gnmi.OC().System().MountPointAny().Available().State()) + utilizeds := mountPointLeafValues(t, gnmiOpts, gnmi.OC().System().MountPointAny().Utilized().State()) + for _, mpName := range mpNames { + mp := &oc.System_MountPoint{Name: ygot.String(mpName)} + if v, ok := sizes[mpName]; ok { + mp.Size = ygot.Uint64(v) + } + if v, ok := availables[mpName]; ok { + mp.Available = ygot.Uint64(v) + } + if v, ok := utilizeds[mpName]; ok { + mp.Utilized = ygot.Uint64(v) + } + mountPoints = append(mountPoints, mp) + } + } else { + mountPoints = gnmi.GetAll(t, gnmiOpts, gnmi.OC().System().MountPointAny().State()) + } + if len(mountPoints) == 0 { + t.Fatalf("No storage mount points reported under /system/mount-points/mount-point/state") + } + + var foundUsableCapacity bool + for _, mp := range mountPoints { + if validateMountPoint(t, mp) { + foundUsableCapacity = true + } + } + if !foundUsableCapacity { + t.Errorf("No mount point reported non-zero size and available capacity") + } +} + +// mountPointLeafValues runs a single-leaf wildcard query over +// /system/mount-points/mount-point[name=*]/state/ and returns the +// present values keyed by mount-point name. +func mountPointLeafValues(t *testing.T, dev gnmi.DeviceOrOpts, q ygnmi.WildcardQuery[uint64]) map[string]uint64 { + t.Helper() + vals := make(map[string]uint64) + for _, v := range gnmi.LookupAll(t, dev, q) { + val, ok := v.Val() + if !ok { + continue + } + for _, elem := range v.Path.GetElem() { + if elem.GetName() == "mount-point" { + if name := elem.GetKey()["name"]; name != "" { + vals[name] = val + } + break + } + } + } + return vals +} + +// putFileComplete executes a complete three-phase client-streaming +// gnoi.file.File.Put RPC (Open -> Contents chunks -> Hash -> CloseAndRecv). +func putFileComplete(ctx context.Context, t *testing.T, fc fpb.FileClient, spec fileSpec) { + t.Helper() + stream, err := fc.Put(rpcContext(ctx, t)) + if err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to open stream: %v", spec.path, err) + } + + openReq := &fpb.PutRequest{ + Request: &fpb.PutRequest_Open{ + Open: &fpb.PutRequest_Details{ + RemoteFile: spec.path, + Permissions: spec.perms, + }, + }, + } + if err := stream.Send(openReq); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{open}: %v", spec.path, err) + } + + step := spec.chunkSize + if step <= 0 { + step = chunkSize64KB + } + for offset := 0; offset < len(spec.payload); offset += step { + end := offset + step + if end > len(spec.payload) { + end = len(spec.payload) + } + chunkReq := &fpb.PutRequest{ + Request: &fpb.PutRequest_Contents{ + Contents: spec.payload[offset:end], + }, + } + if err := stream.Send(chunkReq); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{contents} at offset %d: %v", spec.path, offset, err) + } + } + + hashReq := &fpb.PutRequest{ + Request: &fpb.PutRequest_Hash{ + Hash: &tpb.HashType{ + Method: spec.hashMethod, + Hash: spec.wantDigest, + }, + }, + } + if err := stream.Send(hashReq); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send final PutRequest{hash}: %v", spec.path, err) + } + + if _, err := stream.CloseAndRecv(); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) CloseAndRecv() failed: got error %v (code %v), want StatusCode.OK", spec.path, err, status.Code(err)) + } +} + +// verifyFileStat checks gnoi.file.File.Stat for a single committed file path, +// verifying path, size, permissions, last_modified, and umask. +func verifyFileStat(ctx context.Context, t *testing.T, fc fpb.FileClient, spec fileSpec) { + t.Helper() + resp, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: spec.path}) + if err != nil { + t.Fatalf("gnoi.file.File.Stat(%q) failed: %v", spec.path, err) + } + stats := resp.GetStats() + if len(stats) == 0 { + t.Fatalf("gnoi.file.File.Stat(%q) returned 0 StatInfo entries, want >= 1", spec.path) + } + + info := stats[0] + t.Logf("File.Stat(%q): path=%q size=%d permissions=%d umask=%d last_modified=%d", + spec.path, info.GetPath(), info.GetSize(), info.GetPermissions(), info.GetUmask(), info.GetLastModified()) + + if got := info.GetPath(); got != spec.path && baseName(got) != spec.name { + t.Errorf("File.Stat(%q) StatInfo.path = %q, want %q", spec.path, got, spec.path) + } + if gotSize, wantSize := info.GetSize(), uint64(len(spec.payload)); gotSize != wantSize { + t.Errorf("File.Stat(%q) StatInfo.size = %d, want %d", spec.path, gotSize, wantSize) + } + if info.GetLastModified() == 0 { + t.Errorf("File.Stat(%q) StatInfo.last_modified = 0, want > 0", spec.path) + } + if masked, ok := permissionsMatch(spec.perms, info.GetPermissions(), info.GetUmask()); !ok { + t.Errorf("File.Stat(%q) StatInfo.permissions = %d, want %d (octal digits, no base conversion) or %d (requested permissions with umask %d applied)", spec.path, info.GetPermissions(), spec.perms, masked, info.GetUmask()) + } +} + +// permissionsMatch reports whether a StatInfo.permissions value matches the +// permissions requested in PutRequest.Details. Both values, and the umask, use +// the gnoi/file/file.proto octal-digit encoding (e.g. UNIX mode 0644 is carried +// as 644), so the reported value may equal the requested value or the requested +// value with the reported umask applied (permissions & ~umask). A umask of 0 is +// valid. It also returns the umask-applied value for diagnostics. +func permissionsMatch(want, got, umask uint32) (uint32, bool) { + if got == want { + return want, true + } + wantMode, err := strconv.ParseUint(strconv.FormatUint(uint64(want), 10), 8, 32) + if err != nil { + return want, false + } + umaskMode, err := strconv.ParseUint(strconv.FormatUint(uint64(umask), 10), 8, 32) + if err != nil { + return want, false + } + maskedDigits, err := strconv.ParseUint(strconv.FormatUint(wantMode&^umaskMode, 8), 10, 32) + if err != nil { + return want, false + } + return uint32(maskedDigits), got == uint32(maskedDigits) +} + +// baseName returns the final element of a DUT file path, handling both +// "/dir/name" and ":name" (for example "harddisk:file.txt") forms. +func baseName(p string) string { + if i := strings.LastIndexAny(p, "/:"); i >= 0 { + return p[i+1:] + } + return p +} + +// verifyDirectoryStat checks gnoi.file.File.Stat on the parent scratch +// directory and confirms all expected files are listed with matching byte sizes. +func verifyDirectoryStat(ctx context.Context, t *testing.T, fc fpb.FileClient, scratchDir string, specs []fileSpec) { + t.Helper() + resp, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: scratchDir}) + if err != nil { + t.Fatalf("gnoi.file.File.Stat(%q) on directory failed: %v", scratchDir, err) + } + foundByName := make(map[string]*fpb.StatInfo) + for _, st := range resp.GetStats() { + foundByName[baseName(st.GetPath())] = st + } + for _, spec := range specs { + st, ok := foundByName[spec.name] + if !ok { + t.Errorf("Directory File.Stat(%q) missing expected file %q", scratchDir, spec.name) + continue + } + if gotSize, wantSize := st.GetSize(), uint64(len(spec.payload)); gotSize != wantSize { + t.Errorf("Directory File.Stat(%q) entry %q size = %d, want %d", scratchDir, spec.name, gotSize, wantSize) + } + } +} + +// verifyErrorDigestHex asserts that every hex digest rendered after a digest +// label in a File.Put hash-mismatch error message uses the fixed-length, +// zero-padded unsigned %02x encoding (64 chars for SHA256, 32 chars for MD5), +// and that any digest other than the all-zero digest sent by the client equals +// the expected digest of the transmitted payload. +func verifyErrorDigestHex(t *testing.T, errMsg, wantHex string) { + t.Helper() + zeroHex := strings.Repeat("0", len(wantHex)) + for _, m := range errorDigestHexPattern.FindAllStringSubmatch(errMsg, -1) { + gotHex := strings.ToLower(m[1]) + switch { + case len(gotHex) != len(wantHex): + t.Errorf("gNOI-5.4.3 Defect: error message %q contains digest %q with %d hex chars, want fixed-length zero-padded %d-char hex (e.g. %q)", errMsg, m[1], len(gotHex), len(wantHex), wantHex) + case gotHex != zeroHex && gotHex != wantHex: + t.Errorf("gNOI-5.4.3 Defect: error message %q contains digest %q, want the all-zero client digest or the payload digest %q", errMsg, m[1], wantHex) + } + } +} + +// verifyFileStatNotFound asserts that gnoi.file.File.Stat returns a non-OK +// gRPC error (for example NOT_FOUND) for a removed or uncommitted file path. +// Server or session failures (UNAVAILABLE, UNIMPLEMENTED, PERMISSION_DENIED, +// UNAUTHENTICATED) and client timeouts are not accepted as file-absent results. +func verifyFileStatNotFound(ctx context.Context, t *testing.T, fc fpb.FileClient, path string) { + t.Helper() + resp, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: path}) + if err == nil { + t.Fatalf("gnoi.file.File.Stat(%q) succeeded with %d entries (%+v), want gRPC NOT_FOUND error", path, len(resp.GetStats()), resp.GetStats()) + } + if isRPCTimeout(err) { + t.Errorf("gnoi.file.File.Stat(%q) did not complete within %v: %v, want gRPC NOT_FOUND error", path, rpcTimeout, err) + return + } + switch code := status.Code(err); code { + case codes.NotFound: + case codes.Unavailable, codes.Unimplemented, codes.PermissionDenied, codes.Unauthenticated: + t.Errorf("gnoi.file.File.Stat(%q) returned %v (%v): server or session failure, not a valid file-absent result", path, code, err) + default: + t.Logf("gnoi.file.File.Stat(%q) returned non-OK code %v (%v)", path, code, err) + } +} + +// verifyFileGet downloads a file via server-streaming gnoi.file.File.Get, +// reassembles all GetResponse{contents} chunks, and validates both byte-for-byte +// payload equality and the trailing GetResponse{hash} digest (including +// fixed-length unsigned %02x hex formatting across bytes >= 0x80 and < 0x10). +func verifyFileGet(ctx context.Context, t *testing.T, fc fpb.FileClient, spec fileSpec) { + t.Helper() + stream, err := fc.Get(rpcContext(ctx, t), &fpb.GetRequest{RemoteFile: spec.path}) + if err != nil { + t.Fatalf("gnoi.file.File.Get(%q) failed to start stream: %v", spec.path, err) + } + + var received bytes.Buffer + var trailingHash *tpb.HashType + for { + resp, err := stream.Recv() + if err == io.EOF { + break + } + if err != nil { + t.Fatalf("gnoi.file.File.Get(%q) stream.Recv() failed: %v", spec.path, err) + } + switch r := resp.GetResponse().(type) { + case *fpb.GetResponse_Contents: + received.Write(r.Contents) + case *fpb.GetResponse_Hash: + trailingHash = r.Hash + } + } + + if !bytes.Equal(received.Bytes(), spec.payload) { + t.Errorf("gnoi.file.File.Get(%q) payload mismatch: got %d bytes, want %d bytes", spec.path, received.Len(), len(spec.payload)) + } + + if trailingHash == nil { + t.Fatalf("gnoi.file.File.Get(%q) stream closed without sending trailing GetResponse{hash}", spec.path) + } + + gotBytes := trailingHash.GetHash() + gotHex := hex.EncodeToString(gotBytes) + + // Verify the returned HashType matches the expected digest for its reported + // HashMethod (or the spec's HashMethod). + wantMethodDigest, wantMethodHex := computeDigest(t, spec.payload, trailingHash.GetMethod()) + wantHexLen := len(wantMethodDigest) * 2 + if len(gotHex) != wantHexLen { + t.Errorf("gnoi.file.File.Get(%q) formatted hex digest length = %d (%q), want exact fixed length %d", spec.path, len(gotHex), gotHex, wantHexLen) + } + if !bytes.Equal(gotBytes, wantMethodDigest) || gotHex != wantMethodHex { + t.Errorf("gnoi.file.File.Get(%q) trailing hash mismatch (method=%v): got %q, want %q", spec.path, trailingHash.GetMethod(), gotHex, wantMethodHex) + } +} + +// TestGNOIFileConformance executes gNOI-5.4: gNOI File Put and Stat Protocol +// Conformance sequentially across subtests gNOI-5.4.1 through gNOI-5.4.5. +func TestGNOIFileConformance(t *testing.T) { + ctx := context.Background() + dut := ondatra.DUT(t, "dut") + fc := dut.RawAPIs().GNOI(t).File() + + var filesRemoved bool + scratchDir := setupEnvironment(ctx, t, dut, fc, &filesRemoved) + + // Construct the 3 deterministic baseline fileSpecs defined in the README. + payloadABytes := []byte(payloadAContent) + payloadADigest, payloadAHex := computeDigest(t, payloadABytes, tpb.HashType_SHA256) + if payloadAHex != payloadASHA256Hex { + t.Fatalf("Internal sanity check failed for Payload A SHA256: got %q, want %q", payloadAHex, payloadASHA256Hex) + } + + payloadBBytes := []byte(payloadBContent) + payloadBDigest, payloadBHex := computeDigest(t, payloadBBytes, tpb.HashType_MD5) + if payloadBHex != payloadBMD5Hex { + t.Fatalf("Internal sanity check failed for Payload B MD5: got %q, want %q", payloadBHex, payloadBMD5Hex) + } + + payloadCBytes := bytes.Repeat([]byte(payloadCRecord), payloadCRecordCount) + payloadCDigest, payloadCHex := computeDigest(t, payloadCBytes, tpb.HashType_SHA256) + if payloadCHex != payloadCSHA256Hex { + t.Fatalf("Internal sanity check failed for Payload C SHA256: got %q, want %q", payloadCHex, payloadCSHA256Hex) + } + if len(payloadCBytes) != multiChunkTotal { + t.Fatalf("Internal sanity check failed for Payload C size: got %d bytes, want %d (%d x %d bytes)", len(payloadCBytes), multiChunkTotal, multiChunkCount, chunkSize64KB) + } + + baselineSpecs := []fileSpec{ + { + name: fileNameRoundtripSHA256, + path: path.Join(scratchDir, fileNameRoundtripSHA256), + perms: payloadAPerms, + payload: payloadABytes, + chunkSize: chunkSize64KB, + hashMethod: tpb.HashType_SHA256, + wantDigest: payloadADigest, + wantHex: payloadAHex, + }, + { + name: fileNameRoundtripMD5, + path: path.Join(scratchDir, fileNameRoundtripMD5), + perms: payloadBPerms, + payload: payloadBBytes, + chunkSize: chunkSize64KB, + hashMethod: tpb.HashType_MD5, + wantDigest: payloadBDigest, + wantHex: payloadBHex, + }, + { + name: fileNameMultiChunk256K, + path: path.Join(scratchDir, fileNameMultiChunk256K), + perms: payloadCPerms, + payload: payloadCBytes, + chunkSize: chunkSize64KB, + hashMethod: tpb.HashType_SHA256, + wantDigest: payloadCDigest, + wantHex: payloadCHex, + }, + } + + var scaleSpecs []fileSpec + for i := 1; i <= scaleFileCount; i++ { + name := fmt.Sprintf("gnoi_conformance_scale_%02d.txt", i) + content := []byte(fmt.Sprintf("gnoi-scale-file-%02d-ipv4-198.51.100.%d-ipv6-2001:db8:100::%x\n", i, i, i)) + method := tpb.HashType_SHA256 + if i%2 == 0 { + method = tpb.HashType_MD5 + } + digest, hexStr := computeDigest(t, content, method) + scaleSpecs = append(scaleSpecs, fileSpec{ + name: name, + path: path.Join(scratchDir, name), + perms: payloadAPerms, + payload: content, + chunkSize: chunkSize64KB, + hashMethod: method, + wantDigest: digest, + wantHex: hexStr, + }) + } + + // gNOI-5.4.1 - Positive Single-Chunk and Multi-Chunk gNOI File.Put, + // File.Stat, and File.Get Baseline with SHA-256 and MD5 Digest Verification. + t.Run("gNOI-5.4.1_Positive_File_Put_Stat_Get_Baseline", func(t *testing.T) { + t.Log("gNOI-5.4.1 - Step 1: Upload baseline single-chunk (SHA256, MD5) and multi-chunk (256 KB) files via gnoi.file.File.Put") + for _, spec := range baselineSpecs { + putFileComplete(ctx, t, fc, spec) + } + + t.Log("gNOI-5.4.1 - Step 2: Verify file metadata via gnoi.file.File.Stat for each file and parent directory") + for _, spec := range baselineSpecs { + verifyFileStat(ctx, t, fc, spec) + } + verifyDirectoryStat(ctx, t, fc, scratchDir, baselineSpecs) + + t.Log("gNOI-5.4.1 - Step 3: Verify streamed payload and fixed-length unsigned digest via gnoi.file.File.Get") + for _, spec := range baselineSpecs { + verifyFileGet(ctx, t, fc, spec) + } + }) + + // gNOI-5.4.2 - Negative gNOI File.Put Stream Closed Without Trailing + // HashType Message and Existing-File Preservation. + t.Run("gNOI-5.4.2_Negative_File_Put_Without_Trailing_HashType", func(t *testing.T) { + incompletePath := path.Join(scratchDir, fileNameIncompleteNoHash) + + t.Log("gNOI-5.4.2 - Step 1: Open gnoi.file.File.Put stream, send Open + Contents, and close stream without trailing PutRequest{hash}") + stream, err := fc.Put(rpcContext(ctx, t)) + if err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to open stream: %v", incompletePath, err) + } + if err := stream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Open{ + Open: &fpb.PutRequest_Details{ + RemoteFile: incompletePath, + Permissions: payloadAPerms, + }, + }, + }); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{open}: %v", incompletePath, err) + } + if err := stream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Contents{ + Contents: []byte(incompleteNoHashPayload), + }, + }); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{contents}: %v", incompletePath, err) + } + + t.Log("gNOI-5.4.2 - Step 2: Dual assertion — verify CloseAndRecv returns non-OK gRPC error AND temporary file is removed") + putResp, putErr := stream.CloseAndRecv() + switch { + case putErr == nil || status.Code(putErr) == codes.OK: + t.Errorf("gNOI-5.4.2 Defect: gnoi.file.File.Put(%q) closed without trailing PutRequest{hash} returned StatusCode.OK (resp=%+v), want non-OK gRPC error (INVALID_ARGUMENT, ABORTED, or FAILED_PRECONDITION)", incompletePath, putResp) + case isRPCTimeout(putErr): + t.Errorf("gNOI-5.4.2 Defect: DUT did not terminate gnoi.file.File.Put(%q) within %v after the client half-closed the stream without trailing PutRequest{hash}: %v, want non-OK gRPC error (INVALID_ARGUMENT, ABORTED, or FAILED_PRECONDITION)", incompletePath, rpcTimeout, putErr) + default: + t.Logf("gnoi.file.File.Put(%q) without trailing hash properly rejected with status=%v: %v", incompletePath, status.Code(putErr), putErr) + } + + verifyFileStatNotFound(ctx, t, fc, incompletePath) + getStream, getErr := fc.Get(rpcContext(ctx, t), &fpb.GetRequest{RemoteFile: incompletePath}) + if getErr == nil { + _, recvErr := getStream.Recv() + switch { + case recvErr == nil || recvErr == io.EOF: + t.Errorf("gnoi.file.File.Get(%q) succeeded on incomplete file closed without hash, want NOT_FOUND error", incompletePath) + case isRPCTimeout(recvErr): + t.Errorf("gnoi.file.File.Get(%q) did not complete within %v: %v, want NOT_FOUND error", incompletePath, rpcTimeout, recvErr) + } + } else if isRPCTimeout(getErr) { + t.Errorf("gnoi.file.File.Get(%q) did not complete within %v: %v, want NOT_FOUND error", incompletePath, rpcTimeout, getErr) + } + + t.Log("gNOI-5.4.2 - Step 3: Verify existing committed baseline files from gNOI-5.4.1 remain intact") + for _, spec := range baselineSpecs { + verifyFileStat(ctx, t, fc, spec) + verifyFileGet(ctx, t, fc, spec) + } + }) + + // gNOI-5.4.3 - Negative gNOI File.Put Mismatched HashType Digest Rejection + // and Error Hex Formatting Validation. + t.Run("gNOI-5.4.3_Negative_File_Put_Mismatched_HashType_Digest", func(t *testing.T) { + mismatchPath := path.Join(scratchDir, fileNameHashMismatch) + + mismatchCases := []struct { + desc string + stepLabel string + payload []byte + method tpb.HashType_HashMethod + zeroDigest []byte + wantHex string + }{ + { + desc: "SHA256_Mismatched_AllZero_Digest", + stepLabel: "gNOI-5.4.3 - Steps 1 & 2 (SHA256)", + payload: payloadABytes, + method: tpb.HashType_SHA256, + zeroDigest: make([]byte, 32), + wantHex: payloadASHA256Hex, + }, + { + desc: "MD5_Mismatched_AllZero_Digest", + stepLabel: "gNOI-5.4.3 - Step 3 (MD5)", + payload: payloadBBytes, + method: tpb.HashType_MD5, + zeroDigest: make([]byte, 16), + wantHex: payloadBMD5Hex, + }, + { + desc: "UNSPECIFIED_HashMethod_Rejected", + stepLabel: "gNOI-5.4.3 - Step 3b (UNSPECIFIED HashMethod)", + payload: payloadABytes, + method: tpb.HashType_UNSPECIFIED, + zeroDigest: make([]byte, 32), + wantHex: payloadASHA256Hex, + }, + } + + for _, tc := range mismatchCases { + t.Run(tc.desc, func(t *testing.T) { + t.Logf("%s: Transmit gnoi.file.File.Put with intentionally mismatched %v digest", tc.stepLabel, tc.method) + stream, err := fc.Put(rpcContext(ctx, t)) + if err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to open stream: %v", mismatchPath, err) + } + if err := stream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Open{ + Open: &fpb.PutRequest_Details{ + RemoteFile: mismatchPath, + Permissions: payloadAPerms, + }, + }, + }); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{open}: %v", mismatchPath, err) + } + if err := stream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Contents{ + Contents: tc.payload, + }, + }); err != nil { + t.Fatalf("gnoi.file.File.Put(%q) failed to send PutRequest{contents}: %v", mismatchPath, err) + } + if err := stream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Hash{ + Hash: &tpb.HashType{ + Method: tc.method, + Hash: tc.zeroDigest, + }, + }, + }); err != nil && err != io.EOF { + t.Logf("stream.Send(PutRequest{hash}) returned immediate error: %v", err) + } + + _, putErr := stream.CloseAndRecv() + switch { + case putErr == nil || status.Code(putErr) == codes.OK: + t.Errorf("gnoi.file.File.Put(%q) with mismatched %v digest returned StatusCode.OK, want non-OK gRPC error", mismatchPath, tc.method) + case isRPCTimeout(putErr): + t.Errorf("gNOI-5.4.3 Defect: DUT did not complete gnoi.file.File.Put(%q) with mismatched %v digest within %v: %v, want non-OK gRPC error", mismatchPath, tc.method, rpcTimeout, putErr) + default: + errMsg := status.Convert(putErr).Message() + t.Logf("gnoi.file.File.Put(%q) with mismatched %v digest rejected with code=%v message=%q", mismatchPath, tc.method, status.Code(putErr), errMsg) + if signExtensionHexPattern.MatchString(errMsg) { + t.Errorf("gNOI-5.4.3 Defect: error message %q contains signed-char ffffff sign-extension on digest bytes >= 0x80 (want clean %d-char hex %q)", errMsg, len(tc.wantHex), tc.wantHex) + } + if tc.method != tpb.HashType_UNSPECIFIED { + verifyErrorDigestHex(t, errMsg, tc.wantHex) + } + } + + verifyFileStatNotFound(ctx, t, fc, mismatchPath) + }) + } + + t.Log("gNOI-5.4.3 - Step 4: Confirm gNOI-5.4.1 baseline files remain intact") + for _, spec := range baselineSpecs { + verifyFileStat(ctx, t, fc, spec) + } + }) + + // gNOI-5.4.4 - Modest Scale: Multi-File Batch Staging (10 Files), Directory + // File.Stat, and Mount-Point Telemetry. + t.Run("gNOI-5.4.4_Modest_Scale_Multi_File_Batch_And_Telemetry", func(t *testing.T) { + t.Log("gNOI-5.4.4 - Step 1: Stage 10 additional files across SHA256 and MD5") + for _, spec := range scaleSpecs { + putFileComplete(ctx, t, fc, spec) + } + + t.Log("gNOI-5.4.4 - Step 2: Verify directory-level File.Stat across all 13 committed files and streamed File.Get on all 10 scale files") + allCommitted := append([]fileSpec{}, baselineSpecs...) + allCommitted = append(allCommitted, scaleSpecs...) + verifyDirectoryStat(ctx, t, fc, scratchDir, allCommitted) + + for _, spec := range scaleSpecs { + verifyFileStat(ctx, t, fc, spec) + verifyFileGet(ctx, t, fc, spec) + } + + t.Log("gNOI-5.4.4 - Step 3: Verify storage mount-point telemetry via gNMI Subscribe ONCE (gnmi.GetAll / gnmi.LookupAll)") + verifyMountPointsTelemetry(t, dut) + }) + + // gNOI-5.4.5 - Protocol-Level Mandatory Negative Cases and Final + // File.Remove Verification. + t.Run("gNOI-5.4.5_Protocol_Negative_Cases_And_Final_Remove", func(t *testing.T) { + t.Log("gNOI-5.4.5 - Step 1: Negative Case — Protocol sequence violation (PutRequest{contents} sent before PutRequest{open})") + seqStream, err := fc.Put(rpcContext(ctx, t)) + if err != nil { + t.Fatalf("gnoi.file.File.Put failed to open stream: %v", err) + } + _ = seqStream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Contents{ + Contents: []byte(contentsBeforeOpenData), + }, + }) + if _, seqErr := seqStream.CloseAndRecv(); seqErr == nil || status.Code(seqErr) == codes.OK { + t.Errorf("gnoi.file.File.Put with PutRequest{contents} sent before PutRequest{open} returned StatusCode.OK, want non-OK gRPC error") + } else if isRPCTimeout(seqErr) { + t.Errorf("gnoi.file.File.Put with PutRequest{contents} sent before PutRequest{open} did not complete within %v: %v, want non-OK gRPC error", rpcTimeout, seqErr) + } else { + t.Logf("PutRequest{contents} before PutRequest{open} properly rejected with code=%v: %v", status.Code(seqErr), seqErr) + } + + t.Log("gNOI-5.4.5 - Step 2: Negative Case — Invalid remote_file (empty, relative, and existing directory) in PutRequest{open}") + for _, badPutPath := range []string{"", relativePutFilePath, scratchDir} { + badStream, err := fc.Put(rpcContext(ctx, t)) + if err != nil { + t.Fatalf("gnoi.file.File.Put failed to open stream: %v", err) + } + _ = badStream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Open{ + Open: &fpb.PutRequest_Details{ + RemoteFile: badPutPath, + Permissions: payloadAPerms, + }, + }, + }) + _ = badStream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Contents{ + Contents: payloadABytes, + }, + }) + _ = badStream.Send(&fpb.PutRequest{ + Request: &fpb.PutRequest_Hash{ + Hash: &tpb.HashType{ + Method: tpb.HashType_SHA256, + Hash: payloadADigest, + }, + }, + }) + if _, putErr := badStream.CloseAndRecv(); putErr == nil || status.Code(putErr) == codes.OK { + t.Errorf("gnoi.file.File.Put(remote_file=%q) returned StatusCode.OK, want non-OK gRPC error (remote_file must be an absolute file path)", badPutPath) + } else if isRPCTimeout(putErr) { + t.Errorf("gnoi.file.File.Put(remote_file=%q) did not complete within %v: %v, want non-OK gRPC error (remote_file must be an absolute file path)", badPutPath, rpcTimeout, putErr) + } else { + t.Logf("gnoi.file.File.Put(remote_file=%q) properly rejected with code=%v: %v", badPutPath, status.Code(putErr), putErr) + } + } + if _, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: scratchDir}); err != nil { + t.Errorf("gnoi.file.File.Stat(%q) failed after File.Put to the directory path: %v, want scratch directory to remain intact", scratchDir, err) + } + + t.Log("gNOI-5.4.5 - Step 3: Negative Case — File.Stat, File.Get, File.Remove, and File.TransferToRemote on non-existent, empty, relative, and directory paths") + nonExistentPath := path.Join(scratchDir, fileNameNonExistent) + + for _, badStatPath := range []string{"", relativeTestFilePath} { + if statResp, statErr := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: badStatPath}); statErr == nil || status.Code(statErr) == codes.OK { + t.Errorf("gnoi.file.File.Stat(%q) returned StatusCode.OK (%+v), want non-OK gRPC error (INVALID_ARGUMENT or NOT_FOUND)", badStatPath, statResp) + } else if isRPCTimeout(statErr) { + t.Errorf("gnoi.file.File.Stat(%q) did not complete within %v: %v, want non-OK gRPC error (INVALID_ARGUMENT or NOT_FOUND)", badStatPath, rpcTimeout, statErr) + } else { + t.Logf("gnoi.file.File.Stat(%q) properly rejected with code=%v: %v", badStatPath, status.Code(statErr), statErr) + } + } + + for _, badGetPath := range []string{nonExistentPath, "", relativeTestFilePath} { + getStream, getErr := fc.Get(rpcContext(ctx, t), &fpb.GetRequest{RemoteFile: badGetPath}) + if getErr == nil { + _, recvErr := getStream.Recv() + if recvErr == nil || recvErr == io.EOF { + t.Errorf("gnoi.file.File.Get(%q) succeeded, want non-OK gRPC error", badGetPath) + } else if isRPCTimeout(recvErr) { + t.Errorf("gnoi.file.File.Get(%q) did not complete within %v: %v, want non-OK gRPC error", badGetPath, rpcTimeout, recvErr) + } else { + t.Logf("gnoi.file.File.Get(%q) properly rejected on Recv() with code=%v: %v", badGetPath, status.Code(recvErr), recvErr) + } + } else if isRPCTimeout(getErr) { + t.Errorf("gnoi.file.File.Get(%q) did not complete within %v: %v, want non-OK gRPC error", badGetPath, rpcTimeout, getErr) + } else { + t.Logf("gnoi.file.File.Get(%q) properly rejected with code=%v: %v", badGetPath, status.Code(getErr), getErr) + } + } + + for _, badRmPath := range []string{nonExistentPath, "", scratchDir} { + if _, rmErr := fc.Remove(rpcContext(ctx, t), &fpb.RemoveRequest{RemoteFile: badRmPath}); rmErr == nil || status.Code(rmErr) == codes.OK { + t.Errorf("gnoi.file.File.Remove(%q) returned StatusCode.OK, want non-OK gRPC error", badRmPath) + } else if isRPCTimeout(rmErr) { + t.Errorf("gnoi.file.File.Remove(%q) did not complete within %v: %v, want non-OK gRPC error", badRmPath, rpcTimeout, rmErr) + } else { + t.Logf("gnoi.file.File.Remove(%q) properly rejected with code=%v: %v", badRmPath, status.Code(rmErr), rmErr) + } + } + if _, err := fc.Stat(rpcContext(ctx, t), &fpb.StatRequest{Path: scratchDir}); err != nil { + t.Errorf("gnoi.file.File.Stat(%q) failed after File.Remove on the directory path: %v, want scratch directory to remain intact", scratchDir, err) + } + + transferReqs := []*fpb.TransferToRemoteRequest{ + {}, + {LocalPath: nonExistentPath}, + } + for _, trReq := range transferReqs { + if _, trErr := fc.TransferToRemote(rpcContext(ctx, t), trReq); trErr == nil || status.Code(trErr) == codes.OK { + t.Errorf("gnoi.file.File.TransferToRemote(%+v) returned StatusCode.OK, want non-OK gRPC error (INVALID_ARGUMENT, NOT_FOUND, or UNIMPLEMENTED)", trReq) + } else if isRPCTimeout(trErr) { + t.Errorf("gnoi.file.File.TransferToRemote(%+v) did not complete within %v: %v, want non-OK gRPC error (INVALID_ARGUMENT, NOT_FOUND, or UNIMPLEMENTED)", trReq, rpcTimeout, trErr) + } else { + t.Logf("gnoi.file.File.TransferToRemote(%+v) properly rejected with code=%v: %v", trReq, status.Code(trErr), trErr) + } + } + + t.Log("gNOI-5.4.5 - Step 4: Final gnoi.file.File.Remove verification across all 13 committed files") + allCommitted := append([]fileSpec{}, baselineSpecs...) + allCommitted = append(allCommitted, scaleSpecs...) + for _, spec := range allCommitted { + if _, err := fc.Remove(rpcContext(ctx, t), &fpb.RemoveRequest{RemoteFile: spec.path}); err != nil { + t.Errorf("gnoi.file.File.Remove(%q) failed: %v", spec.path, err) + } + verifyFileStatNotFound(ctx, t, fc, spec.path) + } + filesRemoved = true + }) +} diff --git a/feature/gnoi/system/tests/gnoi_file_conformance_test/metadata.textproto b/feature/gnoi/system/tests/gnoi_file_conformance_test/metadata.textproto new file mode 100644 index 00000000000..1974ef40590 --- /dev/null +++ b/feature/gnoi/system/tests/gnoi_file_conformance_test/metadata.textproto @@ -0,0 +1,41 @@ +# proto-file: github.com/openconfig/featureprofiles/proto/metadata.proto +# proto-message: Metadata + +uuid: "8f4b2c71-5d9a-4e3b-9c1e-6a7f8b2d4e50" +plan_id: "gNOI-5.4" +description: "gNOI File Put and Stat Protocol Conformance" +testbed: TESTBED_DUT +platform_exceptions: { + platform: { + vendor: NOKIA + } + deviations: { + explicit_interface_in_default_vrf: true + interface_enabled: true + } +} +platform_exceptions: { + platform: { + vendor: ARISTA + } + deviations: { + default_network_instance: "default" + interface_enabled: true + } +} +platform_exceptions: { + platform: { + vendor: CISCO + } + deviations: { + system_mount_point_state_ft: "ciscoxr-mount-ft" + } +} +platform_exceptions: { + platform: { + vendor: JUNIPER + } + deviations: { + cli_takes_precedence_over_oc: true + } +} diff --git a/testregistry.textproto b/testregistry.textproto index fd99b3c06a1..9ee57bf6c3d 100644 --- a/testregistry.textproto +++ b/testregistry.textproto @@ -2376,6 +2376,12 @@ test: { readme: "https://github.com/openconfig/featureprofiles/blob/main/feature/gnoi/system/tests/copying_debug_files_test/README.md" exec: "https://github.com/openconfig/featureprofiles/blob/main/feature/gnoi/system/tests/copying_debug_files_test/copying_debug_files_test.go" } +test: { + id: "gNOI-5.4" + description: "gNOI File Put and Stat Protocol Conformance" + readme: "https://github.com/openconfig/featureprofiles/blob/main/feature/gnoi/system/tests/gnoi_file_conformance_test/README.md" + exec: "https://github.com/openconfig/featureprofiles/blob/main/feature/gnoi/system/tests/gnoi_file_conformance_test/gnoi_file_conformance_test.go" +} test: { id: "gNOI-6.1" description: "Factory Reset"