Add missing enum-documented query parameters (ValidateSet/ArgumentCompleter) across 7 cmdlets - #20
Merged
dmann000 merged 9 commits intoJul 22, 2026
Conversation
The array-connections/performance/replication endpoint documents a spec-confirmed type query parameter (all/file-system/object-store) since REST 2.0, but the cmdlet never exposed it. Verified against tools/specs/ (28 cached versions, 2.0-2.27): the value list is byte-identical across every version, so a client-side ValidateSet is safe per this project's stability rule. Adds Tests/Get-PfbArrayConnectionPerformanceReplication.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, pass-through of a valid value, and omission of -Type from the query string when unspecified. Live-verified against FB-A (10.21.243.66): all/file-system/object-store each return real, distinct data (file-system/object-store counters selectively blank out per type); an invalid value now throws client-side before any HTTP call.
The arrays/performance/replication endpoint documents a spec-confirmed type query parameter (all/file-system/object-store) since REST 2.0 (shares the Type_for_performance component with array-connections/performance/replication from spec v2.17 onward), but the cmdlet never exposed it. Verified against tools/specs/: byte-identical value list across every version, so a client-side ValidateSet is safe. Adds Tests/Get-PfbArrayPerformanceReplication.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, pass-through of a valid value, and omission of -Type when unspecified. Live-verified against FB-A (10.21.243.66): all/file-system/object-store each return real, distinct data; an invalid value now throws client-side before any HTTP call.
The support/test endpoint documents a spec-confirmed test_type query parameter (all/phonehome/remote-assist) since REST 2.0, but the cmdlet never exposed it or built any query string at all. Verified against tools/specs/: value tokens are byte-identical across every version (prose wording changed cosmetically at v2.17's component refactor, but the values themselves never did), so a client-side ValidateSet is safe. Adds Tests/Test-PfbSupport.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, pass-through of a valid value, and omission of -TestType when unspecified. Live-verified against FB-A (10.21.243.66): phonehome and remote-assist (with an extended HTTP timeout, since this isolated lab has no real phonehome/ remote-assist connectivity and the default 30s timeout was too short) both return real, distinct test_type results; an invalid value now throws client-side before any HTTP call.
The policies-all/members endpoint documents a spec query parameter member_types, but the cmdlet never exposed it. Unlike the other 6 gaps in this batch, verifying tools/specs/ found the value set is NOT stable: it was 4 values (file-systems, file-system-snapshots, file-system-replica-links, object-store-users) from v2.2-v2.16, then grew to 5 at v2.17 adding object-store-accounts, and the spec prose itself uses non-exhaustive "include"/"different endpoints may accept different subsets" wording. Per this project's own established rule (a value set that changed since introduction gets an ArgumentCompleter, not a ValidateSet, even with full history -- see Value-Enum-Extraction-Work.md and the Pester fixture in Build-PfbFieldCmdletMap.Tests.ps1), -MemberType gets a tab-completing ArgumentCompleter offering all 5 known values instead, with no client-side rejection of anything outside that list. This is the first ArgumentCompleter shipped on a Public cmdlet in this module (a prior, larger, version-aware ArgumentCompleter design was evaluated and shelved for a different purpose -- hiding parameter names by array capability, which completers can't do; this one only completes a parameter's value, the case completers are actually built for). Adds Tests/Get-PfbPolicyAllMember.Tests.ps1 (no prior coverage existed) covering the completer offering all 5 values, a value outside the list NOT being rejected, pass-through of valid values comma-joined, and omission of -MemberType when unspecified. Live-verified against FB-A (10.21.243.66): all 5 known values are accepted by the server without error (including object-store-accounts, the value a 4-value ValidateSet would have permanently blocked); a genuinely bogus value is rejected server-side with a clear "Invalid member type" error -- directly confirming the ArgumentCompleter choice over ValidateSet was correct here.
The network-interfaces/trace endpoint documents a spec-confirmed method query parameter (icmp/tcp/udp) since REST 2.6, but the cmdlet never exposed it. Verified against tools/specs/: byte-identical value list across every version it appears in, so a client-side ValidateSet is safe. (The spec also documents fragment_packet, discover_mtu, component_name, port, and resolve_hostname on this endpoint -- out of scope here, this task covers only the method value-enum.) Adds Tests/Invoke-PfbNetworkTrace.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, pass-through of a valid value, and omission of -Method when unspecified. Live-verified against FB-A (10.21.243.66): icmp/tcp/udp each return real, distinct traceroute output (icmp resolves the full path; tcp/udp show the expected blocked hops downstream); an invalid value now throws client-side before any HTTP call.
The file-systems/sessions endpoint documents a spec-confirmed protocols query parameter (nfs/smb) since REST 2.10, but the cmdlet never exposed it. Verified against tools/specs/: byte-identical value tokens across every version, so a client-side ValidateSet is safe despite the spec's non- exhaustive "include" wording (tokens themselves never changed). Adds Tests/Get-PfbFileSystemSession.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, pass-through of valid values comma-joined, and omission of -Protocol when unspecified. Live-verified against FB-A (10.21.243.66): -Protocol nfs and -Protocol smb individually both succeed (0 active sessions in this lab, as expected); an invalid value throws client-side before any HTTP call. Also discovered (sanity note, not a client bug -- confirmed via a raw Invoke-PfbApiRequest call bypassing this cmdlet entirely) that FB-A''s server rejects the comma-joined multi-value form protocols=nfs,smb with "Cannot process more than one name at a time", even with no -Name/-Id supplied -- an apparent server-side limitation on this array/Purity build despite the spec documenting protocols as a comma-separated list.
The DELETE file-systems/sessions endpoint documents a spec-confirmed protocols query parameter (nfs/smb) since REST 2.10 -- the same field as Get-PfbFileSystemSession''s GET side, re-verified separately here since a query parameter existing on GET doesn''t guarantee it exists identically on DELETE (it does: same tokens, distinct Protocols_required shared component from spec v2.17). Verified byte-identical value tokens across every version, so a client-side ValidateSet is safe. Design choice: this cmdlet only ever supported single-target termination via mandatory, mutually-exclusive -Name/-Id. The real endpoint supports filtering independently of names/ids (server can bulk-terminate by protocol alone), but adding that bulk/filter-only mode would be a materially bigger, riskier change to a SupportsShouldProcess/ConfirmImpact=High destructive cmdlet. Added -Protocol as an additional, optional, set-agnostic narrowing filter instead (alongside the existing -Array parameter''s precedent) -- -Name or -Id is still required; -Protocol only narrows an already-selected target. Adds Tests/Remove-PfbFileSystemSession.Tests.ps1 (no prior coverage existed) covering the ValidateSet attribute, rejection of an invalid value with zero API calls, the still-mandatory -Name/-Id requirement even with -Protocol supplied, pass-through of valid values comma-joined alongside both -Name and -Id, omission of -Protocol when unspecified, and -WhatIf making zero calls. Not live-tested against FB-A -- this is a disruptive (ConfirmImpact = ''High'') session-termination operation; per the task instructions, mocked coverage is the verification bar here, and a live test against a real target session requires the user''s direct involvement with a genuinely disposable session.
…remove fake -Id
Live-testing the -Protocol addition from the prior commit against a real array
(sn1-s200-c09-33.fsa.lab) surfaced two real, pre-existing bugs in this cmdlet, neither
introduced by that commit:
1. The server rejects combining `names` with any other query parameter, including
`protocols` -- confirmed live (400: "The passed arguments are mutually exclusive") and
in the spec''s own DELETE description, stable since v2.10: "When `names` is specified, no
other query parameter can be specified." The prior commit''s design (-Protocol as an
*additional* narrowing filter alongside -Name) can never work against a real array.
-Protocol is now its own mutually-exclusive ByProtocol parameter set: a genuine bulk
-terminate-by-protocol mode, matching what the server actually supports (confirmed live:
sending protocols+disruptive=true with no name succeeds).
2. There is no `ids` query parameter on this endpoint in ANY spec version (2.10-2.27
checked) -- -Id was never functional; no session object returned by this API has an
"id" field at all, only a self-contained "name" (e.g. "22517998136858346-smb"). Removed
entirely rather than left as permanently-broken surface.
3. -Name''s own help text was wrong: it claimed to filter by "the name of the file system,"
but live-verified the server rejects a file system name here ("Invalid name specified")
-- it filters by the session''s own generated name, as returned by
Get-PfbFileSystemSession''s Name property. Fixed.
Because -Protocol is now confirmed array-wide and cross-client (no per-client/per-user
filter is exposed by this cmdlet), it also requires an explicit -Force switch, checked
independent of $ConfirmPreference/-Confirm -- so lowering a session''s confirm preference
globally still cannot trigger a bulk purge without deliberate opt-in. The existing
SupportsShouldProcess/ConfirmImpact=High prompt remains in place as an additional,
separate gate.
Tests/Remove-PfbFileSystemSession.Tests.ps1 rewritten: asserts -Id no longer exists, true
parameter-set exclusivity between -Name/-Protocol, the required disruptive=true flag on
the bulk path, the independent -Force gate, and -WhatIf on both paths.
Live-verified against sn1-s200-c09-33.fsa.lab: terminated a real SMB session via the
corrected -Name path (200 OK, session confirmed gone from a follow-up
Get-PfbFileSystemSession call). Did not live-test the -Protocol bulk path -- this is a
shared lab array with other real users'' active sessions, and -Protocol has no per-client
filter to scope a live test safely.
Same underlying bug found while live-testing Remove-PfbFileSystemSession''s sibling cmdlet: there is no `ids` query parameter on GET file-systems/sessions in any spec version (2.10-2.27 checked) -- -Id was never functional, no session object has an "id" field. Removed the ById parameter set entirely. -Name''s help text incorrectly claimed to filter by "file system names" -- live-verified (via the same investigation) that it actually filters by the session''s own generated name (e.g. "22517998136858346-smb"), not a file system name. Fixed the doc text; the underlying `$queryParams[''names'']` wiring was already correct. Unlike the DELETE side, GET''s spec description does not document any mutual-exclusivity restriction between `names` and `protocols` -- Task 6''s -Protocol addition (prior commit) is unaffected and remains combinable with -Name here. Tests/Get-PfbFileSystemSession.Tests.ps1: added assertions that -Id no longer exists and that -Name passes through to the `names` query parameter correctly.
This was referenced Jul 22, 2026
Merged
dmann000
added a commit
that referenced
this pull request
Jul 22, 2026
Bump ModuleVersion 2.1.2 -> 2.2.0 for the API version-awareness feature (PR #21) and the seven feature-gap query-param enums + session-cmdlet fixes (PR #20). Adds the v2.2.0 ReleaseNotes highlight and CHANGELOG entry. Also fixes Publish-Gallery.ps1 so the branded EverpureFBModule package carries Data/ (the capability + version maps). build.ps1 already copies Data/ into the source package; the rebrand step copied only the psm1 + LICENSE, so without this the API version-awareness check would silently no-op on every Gallery install. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
juemerson-at-purestorage
deleted the
feature/add-missing-validateset-query-parameters
branch
August 9, 2026 18:50
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes 7 feature gaps surfaced by the inline-path-parameter coverage-gap fix (
fix/get-pfbarrayspace-type-validateset, PR #15): spec-documented query-parameter enums that had no corresponding cmdlet parameter at all. Each new parameter is purely additive (defaults to "not sent"), verified byte-stable against all 28 cached OpenAPI spec versions (2.0-2.27) before choosingValidateSetvsArgumentCompleter.5 new
ValidateSetparameters:Get-PfbArrayConnectionPerformanceReplication -Type(all/file-system/object-store)Get-PfbArrayPerformanceReplication -Type(all/file-system/object-store)Test-PfbSupport -TestType(all/phonehome/remote-assist)Invoke-PfbNetworkTrace -Method(icmp/tcp/udp)Get-PfbFileSystemSession -Protocol(nfs/smb)1 new
ArgumentCompleter(notValidateSet):Get-PfbPolicyAllMember -MemberType— re-verifying against the specs found this value set is not stable (grew 4→5 values at REST v2.17, addingobject-store-accounts, with non-exhaustive "include"/"subsets" wording). Per this project's own rule (a value set that changed since introduction gets a completer, not a hard-validatingValidateSet), this got a tab-completingArgumentCompleterinstead. Live-verified: the server acceptsobject-store-accounts(which a naive 4-valueValidateSetwould have permanently blocked) and rejects a genuinely bogus value with a clear server-side error.Get-/Remove-PfbFileSystemSession changes
Live-testing
Remove-PfbFileSystemSession -Protocolagainst a real array surfaced two additional pre-existing bugs, fixed here:-Protocolis now its own mutually-exclusive parameter set. The server rejects combiningnameswith any other query parameter (confirmed live: 400 "mutually exclusive"; confirmed in the spec's own DELETE description, stable since v2.10: "Whennamesis specified, no other query parameter can be specified").-Protocolis a genuine bulk-terminate-by-protocol mode (array-wide, all clients, no per-client filter exposed) and now requires an explicit-Forceswitch — checked independent of$ConfirmPreference/-Confirm— in addition to the existingSupportsShouldProcess/ConfirmImpact=Highprompt.-Idparameter from both cmdlets. There is noidsquery parameter onfile-systems/sessionsin any of the 28 cached spec versions (2.10-2.27) — session objects have noidfield at all, only a self-containedname(e.g."22517998136858346-smb").-Idcould never have worked.-Name's help text on both cmdlets — it wrongly claimed to filter by "file system name"; live-verified it actually filters by the session's own generated name (as returned byGet-PfbFileSystemSession'sNameproperty).Test plan
Remove-PfbFileSystemSession -Namepath against a real array — terminated a real SMB session, 200 OK, confirmed gone-Protocolbulk-terminate path not live-tested (shared lab array with other real users' active sessions; no per-client filter to scope a safe live test) — covered by mocked tests only🤖 Generated with Claude Code