Skip to content

V2 follow-ups round 2: enrollment deadline, report-status conflict, DCV domain lookup cache - #41

Open
spbsoluble wants to merge 5 commits into
feat/v2-spec-followupsfrom
feat/v2-followups-round2
Open

spbsoluble wants to merge 5 commits into
feat/v2-spec-followupsfrom
feat/v2-followups-round2

Conversation

@spbsoluble

@spbsoluble spbsoluble commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Plan: issues/0096-v2-followups-round2-plan.md, items 0-3. Stacked on #40.

0. Command's Keyfactor-Enroll timeout (investigation, no code)

Read-only, against kfclab Command 25.5:

  • The 60 s isn't a step field. GET /Workflow/Definitions lists one enrollment definition, the built-in "Global Enrollment Workflow" (0d2c4a1e-…, no template key, published v1): StartNOOP → KeyfactorEnroll (EnrollStep) → EndNOOP. GET /Workflow/Definitions/Steps/EnrollStep shows no configuration parameters at all.
  • It's a global application setting: GET /AppSetting → Id 208, Workflow.General.Timeout, "Workflow Step Run Timeout (seconds)", Type_Int, value 60. It applies to every workflow step, not per template or definition. Changing it doesn't require publishing a definition.
  • No documented maximum. Neither the API (AppSettingResponse has no min/max), the ApplicationSettings DB row, nor the Command docs (Application Settings: Workflow tab; AnyCAGateway REST "Configure CA Plugin", which tells DCV users to raise it) give a range. The "about 120 s" cap is unconfirmed.
  • The 100 s HttpClient is a separate layer. No Command app setting or documented knob for Command's HTTP call into the gateway was found. The plugin's existing 100 s assumption (CommandEnrollmentBudgetSeconds, from a field log) stays as the upper clamp.

Written up in docsource/configuration.md ("Command's workflow step timeout and EnrollmentCallBudgetSeconds").

1. Deadline from Enroll entry

  • New setting EnrollmentCallBudgetSeconds: default 50, 0 = no deadline, negative → 50, clamped to 90 (under the 100 s HttpClient). Docs say to set it about 10 s below Workflow Step Run Timeout.
  • How the deadline reaches the pickups. Enroll starts an EnrollmentDeadline first thing and carries it in an AsyncLocal. The V1 new-enroll, V1 renew and V2 pickups all read it, with no signature changes.
  • What it changes in the pickup. Each wait (the initial 5 s and the gap between polls) is shortened to remaining − 3 s (a margin for the poll itself). The delay after the last poll is skipped, because no poll follows it. When no poll fits, the pickup stops and returns pending with one Information line: elapsed, budget, attempts run.
  • What it doesn't change:
    • Calls already in flight (create, reissue, Submit CSR) are never cut short, and orders are still never retried.
    • PickupRetries=0 still disables the pickup.
    • 0 keeps the old cadence, including the trailing delay.
  • Inline DCV is left unchanged (your decision). It's now listed under Known Limitations.
  • Behaviour change with defaults: skipping the trailing delay makes a default pickup that never issues return about 10 s sooner than before.
  • Test seams: Clock (TimeProvider) and PickupDelayAsync, so the 19 new tests run on a manual clock.

2. Order Fulfilled | Pending for Approver

When orderStatus maps to issued and certificateStatus maps to pending, the mapping returns null, so sync asks Track Order and the pair shows in UnmappedReportStatuses. It's deliberately narrow: Order Accepted | Certificate Revoked and the other disagreeing pairs keep their mapping. Order Accepted | Rejected due to Order Cancellation was re-checked live (Track pending-dcv for 3923286643, 6932127547 and 5519319749) and left alone.

3. SSL.com domain lookup cache

One cache per sync pass, and one per Enroll/GetSingleRecord DCV call: domain (case-insensitive) → row, or "no row". Failures aren't cached. Only DomainId/validatedBy are read from a cached row; the DCV state is still read fresh per order from GET /domains/{id}/dcv. Sync processes rows sequentially (await foreach), so a plain Dictionary. The cache only exists under SUPPORTS_DCV.

Testing

  • Unit tests: dotnet test CERTInext.Tests -c Release 1327 passed (baseline 1296 at a9d4ef6 + 31 new); the DcvSupport=false build runs 1242, all passed.
  • Builds: dotnet build -c Release --no-incremental and the same with -p:DcvSupport=false, 0 warnings / 0 errors each.
  • Existing suites still green: CERTInextCAPluginV2PickupTests, RenewalPickupDcvTests, V2CertificateNotGeneratedTests.

Live results

Item 2: Sync_UnresolvedReportStatuses_Probe, one read-only run. 1434 report rows; 1125823297 is now under "Unresolved" with Track status=issued. Unresolved went from 6 to 7 rows (the other 6 are On Hold | Setup Pending).

Item 2, end to end: V2FulfilledPendingSyncLiveTests (new, opt-in, read-only), one run on 2026-11-15. It runs the real Synchronize path against the live API, with the report listing narrowed to 1125823297 by a forwarding proxy.

  • The client calls were ListOrdersV2Async x1, ResolveAndTrackOrderV2WithFamilyAsync x1 and ResolveAndDownloadCertificateV2Async x1.
  • The order was emitted as issued (40). Before this change it was emitted as pending, with no Track call and no download.
  • The download answered 422 EMS-1165, so the order went out without a certificate body (IssuedNotGeneratedYet=1). CERTInext never generated the certificate, even though the order dates from 2026-06-21, before the sandbox stopped generating. The certificate status "Pending for Approver" looks accurate and Track's issued looks wrong. Recorded as an update to Finding 35 in analysis/v2-api-support-questions.md.

Item 1: on kfclab gateway-certinext, DLL deployed from this branch (net8, DcvSupport=false). Workflow Step Run Timeout was 60 unless noted.

Run Before (plan) Now
New AnyCA_DV SSL enrollment, budget 50 Command failed at 60.2 s HTTP 200, EXTERNAL_VALIDATION, 51.9 s. Enroll took 47.7 s: the pickup started at +4.1 s and all 5 polls fit, with only the last wait shortened (order 6292373831).
Command renew of race-2 (Id 1391), RenewalWindowDays 30 → V2 reissue reissue 25.8 s, Command failed at 60 s HTTP 200, EXTERNAL_VALIDATION, 49.6 s. Reissue POST 20.7 s; pickup started at +21.9 s and was stopped early at 47.3 s, 3 of 5 polls (order 9312165275R001).
Workflow Step Run Timeout 120, budget 90 — HTTP 200, pending, 50.9 s; all 5 polls ran, no early stop (order 3474736592).
  • The 120 s run doesn't show a longer wait. The default PickupRetries/PickupDelay (~50 s now) were the binding limit, not the 90 s budget. It shows only that a raised budget doesn't cut a normal pickup short. Seeing the longer wait needs a run with PickupRetries raised too; I haven't done one.
  • Everything was restored. AppSetting 208 is back at 60. The gateway config was re-PUT (200) without RenewalWindowDays or EnrollmentCallBudgetSeconds, matching the kfclab spec (V2InlineCsr=true, SignerIp from the secret, lookback 72, incremental 60 min, full daily 2:00).
  • The three new orders can't be cleaned up yet. They went issued with certificateState: Approved by System (EMS-1165), so, like PR V2 spec follow-ups: SSL.com DCV, reissue endpoint, revoke fallback, token retry (0094, 0095) #40's stuck orders, they can't be revoked until the sandbox generates certificates again.

Item 3: not verifiable on the sandbox (no SSL.com domains).

Open questions

  • The workflow step timeout maximum is undocumented. Is 90 s the right clamp for the budget, or should a higher Workflow Step Run Timeout be allowed to raise it toward 100 s?
  • Inline DCV during Enroll can still exceed the step timeout (DcvTimeoutMinutes defaults to 10). Should it get a follow-up issue to stop DCV polling at the deadline and leave the TXT record for the sync to finish?
  • Should the default PickupRetries/PickupDelay change now that the deadline bounds them? I left them alone.

spbsoluble and others added 4 commits November 14, 2026 12:50
…ws through Track Order

The report row says fulfilled while the certificate status says pending; Track Order
returns issued (live: 1125823297). Preferring certificateStatus reported the order as
pending and never downloaded the certificate. That one shape (order maps issued,
certificate maps pending) now maps to null so the sync asks Track Order, and the pair
appears in UnmappedReportStatuses. Other disagreements keep their mapping.
FindSslComDomainAsync called GET /domains for every pending domain on every DCV
attempt, so a pass over many orders under one domain repeated the same lookup. A
per-pass cache (one per sync pass, one per Enroll/GetSingleRecord DCV call) keeps
found rows and "no row"; failed lookups aren't cached and fall back to emSign as
before. Only DomainId/validatedBy come from the cached row; DCV state is still read
fresh per order. Sync processes rows sequentially, so a plain dictionary.
…entry

Command fails the Keyfactor-Enroll workflow step at its global Workflow Step Run
Timeout (Workflow.General.Timeout, 60 s by default; the step has no timeout of its
own). The pickup budget (5 s + PickupRetries x PickupDelay, capped at 75 s) was
counted from the start of the pickup, so the create time came on top: on the lab a
new DV order and a reissue (26 s) both reached Command's 60 s, which recorded a
failure while the order went on at CERTInext.

New setting EnrollmentCallBudgetSeconds (default 50, 0 disables, clamped to 90 under
the 100 s HttpClient timeout). Enroll starts an EnrollmentDeadline, carried in an
AsyncLocal to the V1 new/renew and V2 pickups. They shorten waits to keep a 3 s poll
margin, skip the delay after the last poll, and stop with one Information line when
no poll fits. In-flight calls are never cut short; PickupRetries=0 is unchanged;
inline DCV is not bounded (documented as a known limitation).
…prover' order

Opt-in (CERTINEXT_V2_FULFILLED_PENDING_SYNC=1), read-only. A DispatchProxy narrows the
real report listing to one order and forwards every other call to the real client, so
the actual Synchronize path runs live. Asserts the row defers to Track Order, comes out
issued, and has its certificate download attempted. Live 2026-11-15 on 1125823297:
Track issued, download 422 EMS-1165 (never generated), emitted issued without a body.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant