fix: five wire-contract defects in the syslog, replication, quota, object-store and SMTP cmdlets

[juemerson-at-purestorage]

Fixes #100, #101, #103, #87, and #80.

Five independent wire-contract defects, developed on separate branches and merged here as one PR so Reports/ is regenerated exactly once. Each fix keeps its own commit; the merges are --no-ff.

The common thread: every one of these cmdlets sent a query key the endpoint does not declare, or failed to send one it requires. Undeclared query parameters are silently ignored by the array rather than rejected, so all five produced plausible-looking results while doing the wrong thing. The published OpenAPI spec was treated as the authority throughout — no parameter was widened or narrowed on the basis of observed array behaviour.

#103 — Test-PfbSyslogServer tested every server regardless of -Name

/syslog-servers/test declares only X-Request-ID and continuation_token — no names, no ids, in any spec version from 2.0 through 2.28. The cmdlet sent both, so they were discarded and every call tested all configured servers.

-Name and -Id are removed along with their parameter sets. The endpoint offers no scoping and the cmdlet no longer pretends otherwise; the help now says so explicitly, with a Where-Object example for narrowing the returned rows client-side. This is a breaking signature change, and deliberately so — a script passing -Name today is already getting unscoped results, so a hard "parameter cannot be found" is strictly better than the current silence.

The other seven Test-Pfb* cmdlets were audited against their endpoints and are all correct. This was an isolated bug, not a family pattern.

#87 — Get-PfbFileSystemReplicaLinkTransfer sent a dead names key

GET /file-system-replica-links/transfer scopes by names_or_owner_names, not names. The cmdlet routed -Name through Add-PfbCommonQueryParams, which hardcodes the generic names/ids keys, so the filter never reached the wire.

Follows the pattern established by #91: -Name becomes -NameOrOwnerName with [Alias('Name')] for backward compatibility, the query key is set directly instead of through the generic helper, -Id gains pipeline-by-property-name binding, and a new imperative coercion guard catches a piped object stringified to @{name=...} before the request fires.

total_only is declared on this endpoint, so -TotalOnly stays here.

Scope correction worth noting: the issue names two cmdlets, but only one was broken. Remove-PfbFileSystemReplicaLink has never had a -Name parameter and never emitted a names key — all five keys it sends are declared on the DELETE. It is untouched.

#100 — group quota writes put the identity in the body

POST/PATCH/DELETE /quotas/groups identify the target through file_system_names, group_names and gids query parameters; the body carries only quota. The cmdlets were building the identity into the body, so the array never received a file-system identifier at all.

Identity now goes in the query for all three verbs. -GroupName and -GroupId are mutually exclusive parameter sets, and gids is sent as an integer per the schema.

#101 — New-PfbObjectStoreAccountExport could never create an export

Three independent defects, none of which had test coverage:

• It sent names, which POST does not accept — the method identifies by member_names/member_ids and policy_names/policy_ids.
• -Name was the only identifying parameter, and it was the wrong one.
• The body was built as if ($Attributes) { $Attributes } else { @{} }, so the schema-required server reference was never sent unless the caller hand-rolled it.

The parameter surface is rebuilt to match the POST contract: -MemberName/-MemberId, -PolicyName/-PolicyId, -ServerName/-ServerId building the required server body reference, and -ExportEnabled as [Nullable[bool]] guarded by ContainsKey so $false survives. A call supplying no server identity throws before the request fires rather than sending a body the schema rejects.

Design note: this landed as four parameter sets plus two explicit pre-request throws for the policy and server exclusivity, rather than the eight sets a purely declarative encoding would need. Eight sets made the -? help unreadable for a marginal gain, and the throws give better messages than a failed set resolution.

Also here, both opportunistically:

• Update-PfbObjectStoreAccountExport's two help examples documented enabled, which is not a field in the PATCH schema. The field is export_enabled. Examples only — the cmdlet itself was correct.
• Get-PfbObjectStoreAccountExport exposed -TotalOnly, but the GET does not declare total_only. Removed outright, no warning and no runtime throw: the switch is a silent no-op today, so no working script depends on its effect. This is the one -TotalOnly removal in this PR; the rest of that sweep belongs to The -TotalOnly switch is a silent no-op on 27 of the 39 Get-Pfb cmdlets that expose it, because total_only is declared on only 32 endpoints (pre-existing, not a #49 regression) #102.

#80 — consolidate the SMTP cmdlets onto /smtp-servers

Update-PfbSmtp PATCHed a REST 1.12 path that does not exist in 2.x, so it has never worked on a 2.x-negotiated connection — and there was no modern write cmdlet at all, leaving encryption_mode unsettable from the module.

Get-PfbSmtp and Update-PfbSmtp are deleted; Get-PfbSmtpServer stays; Update-PfbSmtpServer is new.

Deletion rather than aliasing loses nothing on the wire — /smtp-servers carries both GET and PATCH from REST 2.0, and its 2.0 writable body is exactly the 1.12 field set (relay_host, sender_domain), with encryption_mode added at 2.15. It is a strict superset from the first 2.x version onward.

Aliasing was rejected because the two endpoints disagree about what name means: /smtp returned the array name, /smtp-servers returns the resource name (management). Anyone reading (Get-PfbSmtp).name through an alias would silently get a different string. A removed cmdlet is an honest break; an alias would have been a quiet one.

No explicit version gate was added for -EncryptionMode. The capability map already records it at 2.15 and Invoke-PfbApiRequest asserts capability on every request, so putting the field in the body is sufficient — the throw fires automatically below 2.15. -ApiVersionOverride is kept as plumbing.

No ValidateSet on -EncryptionMode: the spec says valid values include starttls, which is open-ended, and a ValidateSet would impose a floor the spec does not set.

Tests

Six of the cmdlets touched here had zero test coverage, which is precisely why the bugs shipped. New coverage is part of the fix, not a follow-up.

New files: Test-PfbSyslogServer, Get-PfbFileSystemReplicaLinkTransfer, New-PfbQuotaGroup, QuotaGroup, New-PfbObjectStoreAccountExport, ObjectStoreAccountExport, Get-PfbSmtpServer, Update-PfbSmtpServer.

Each carries a permanent regression guard for the specific dead key it fixes, plus the cases that silently break under truthiness guards (-ExportEnabled:$false, -EncryptionMode '' to clear the value). The sub-2.15 encryption_mode gate is mock-only — no lab array is old enough to exercise it.

Run against the merged tree under both editions:

Scope	pwsh 7	Windows PowerShell 5.1
The 9 test files above	94 passed, 0 failed	94 passed, 0 failed
Drift, field-map, manifest	202 passed, 0 failed	113 passed, 0 failed, 89 skipped

The 5.1 skips are the PS7-only tools/ tests.

Live verification

Verified against real hardware, not just mocks. FB-A (Purity//FB 4.8.2, REST 2.26) covered #87 and #103; FB-B (same version) covered #100, #101 and the #80 read path after FB-A became unavailable mid-run.

#87 — the transfer read returned 42 rows unfiltered and 42 with -Name 'fs-share' on main, confirming the key was ignored. On this branch the same snapshot filter returns 3, a bogus value is rejected with File system does not exist., and -TotalOnly still reports total_item_count: 42.

One thing observed and not explained: the owner form of the filter returns 43 rows against 42 unfiltered — stable across three passes, and above total_item_count. Reported as observed array-side behaviour of the owner form rather than as a regression; main cannot send names_or_owner_names at all, so there is no baseline to compare against.

#100 — the contrast is the evidence. Same call, same array:

Code	Result
main	HTTP 400 File system identifier is required.
this branch	HTTP 400 Failed to create quota, names: pslivetest-grp cannot be mapped to ids using the configured directory server(s).

On main the request carried no file-system identifier at all. Here the array accepted file_system_names, moved on to the group, and quoted the exact group name back — the query keys were parsed and acted on. Both are failures and both are deliberate: the test array's directory service is disabled, so no group name can resolve to a GID there and a successful create was never available. -GroupId could not be exercised for an unrelated tooling limitation.

#101 — full lifecycle. main fails with Object store account export identifier is required.; this branch creates the export, and the response echoes member, policy and server exactly as sent. Read-back by name returns the one row, -ExportEnabled:$false comes back enabled: False, delete removes it, and a follow-up enumeration returns total_item_count: 0. All fixtures cleaned up, no residue.

#80 — Get-PfbSmtpServer verified live, returning name: management, which is the resource-name-vs-array-name difference described above, observed rather than inferred.

Update-PfbSmtpServer has no live coverage. The lab harness denies write verbs for the smtp-servers family, and that is a policy rail rather than an array condition, so no target changes the answer. The write path rests on mocked coverage alone. Flagging it rather than letting the batch read as fully live-verified.

Not in this PR

No version bump and no CHANGELOG entry — those are the maintainer's own call, always separate.

Reports/ is regenerated in a single commit at the end. The deltas track the fixes: uncovered endpoints 96 → 95 as /smtp-servers PATCH becomes covered, gids / member_ids / policy_names / file_system_ids each drop an endpoint as the writes start sending them, total_only's cmdlet count drops 39 → 38, and the two stale Update-PfbSmtp entries against the retired /smtp endpoint are gone. Generated by the tools, no hand edits.

Out of scope and left alone: context_names / allow_errors on any of these endpoints (in-flight Fusion work), the wider -TotalOnly sweep (#102), and the remote_names / remote_ids replication filters (#88).

One follow-up was filed while working through this batch: #106, for the same empty-body pattern that broke #101 appearing in New-PfbObjectStoreAccessPolicyRule and 22 other cmdlets.