Repository navigation
feat(policies): deprecate the v11 policy simulation methods - #244
Merged
Merged
Conversation
A v11.0.0 platform deprecates /api/v1/policies/simulate, /impact-report and /conflicts and removes them in v11.1: every response carries X-AxonFlow-Removed-In: v11.1 and a successor Link naming /api/v1/typed-policies, plus an RFC 9745 Deprecation header once v11.0.0 is tagged. simulatePolicies, getPolicyImpactReport and detectPolicyConflicts, and their Async forms, are now @deprecated with Javadoc saying so. They keep answering until v11.1, but on a v11.0.0 platform their results come from the legacy engine, which no longer decides, so they do not predict what the platform enforces. createPolicyOverride and deletePolicyOverride now document that a v11.0.0 platform retires per-policy overrides and refuses both with LegacyPolicyWriteFrozenException. A stamped route that carries an id is reported once, as its route template, not once per id: the eleven methods that put an id in a static- or dynamic-policy path tag the request with its template, and the once-per-route record keys on it. A source census fails any new such call site that carries no template. The runtime leg v11_deprecations drives the deprecations against a live Evaluation-or-above stack. Refs getaxonflow/axonflow-enterprise#3746 Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>
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
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
A v11.0.0 platform deprecates
POST /api/v1/policies/simulate,/impact-reportand/conflictsand removes them in v11.1 (policypath.RemovalRelease, PRD v11 §1.11). Every response from them carriesX-AxonFlow-Removed-In: v11.1and a successorLinknaming/api/v1/typed-policies, plus an RFC 9745Deprecationheader once v11.0.0 is tagged. This marks the eight methods that reach those routes@Deprecatedwith Javadoc saying so, documents the retired per-policy override writes, and proves both against a live stack. It mirrors getaxonflow/axonflow-sdk-go#233 (87042cb3d).Part of getaxonflow/axonflow-enterprise#3746.
What changes
@Deprecated, with a Javadoc@deprecatednaming the removal release (v11.1), the successor (/api/v1/typed-policies) and theDeprecationheader's arrival at the tag, on all eight methods that reach the three routes:simulatePoliciesandsimulatePoliciesAsync;getPolicyImpactReportandgetPolicyImpactReportAsync;detectPolicyConflicts()anddetectPolicyConflicts(String), and bothAsyncforms. Plain@Deprecated, with nosince(an SDK version is the release's to name) and noforRemoval(the removal is the platform's; the SDK's own removal is not decided). They keep working until v11.1.createPolicyOverrideanddeletePolicyOverridedocument, without being deprecated, that a v11.0.0 platform retires per-policy overrides and refuses both with 409LEGACY_POLICY_WRITE_FROZEN, thrown as D1'sLegacyPolicyWriteFrozenException. The Javadoc quotes the refusal a v11.0.0 platform sends, as measured on the stack below (agent-api'sPerPolicyOverrideRetiredresponse):{"error":{"code":"LEGACY_POLICY_WRITE_FROZEN","message":"Per-policy overrides of system controls are retired in v11: a system control is enabled, disabled or re-actioned in the organization's typed document, in its system_controls section, through the typed authoring route at /api/v1/typed-policies. Session break-glass overrides (ADR-044) are unaffected, and reads on this endpoint are unaffected."}}AxonFlow.noteRouteDeprecation, called fromexecuteHttp; the record is shared with derived clients) already reports each route once per client family. The wire-shape baseline is unchanged (the diff oftests/fixtures/wire-shape-baseline.jsonagainst main is empty, and the validator passes).### Deprecatedwith no version number; a README "v11.0.0 deprecations" section.The Deprecation header, today and at the tag
policypath.DeprecatedSinceis a hand-edited constant that stays empty until v11.0.0 is tagged (platform/shared/policypath/policypath.go:254, guarded bypolicypath_test.go:383), so today the platform sends onlyX-AxonFlow-Removed-In: v11.1and the successorLink. Go #233's live run read exactly that at enterprise857455033; this PR's run reads it again below. The unit test pins today's shape (noDeprecation, reportednull); the leg acceptsDeprecationabsent or@<unix seconds>, so it passes today and at the tag.Field-level verification
X-AxonFlow-Removed-In: v11.1present on each of the three routestheSimulationMethodsWorkAndEachRouteIsReportedOnce(mocked at857455033's shape); leg step 2 (live)Linkpresent, exactly/api/v1/typed-policiesDeprecationabsent (today)null; leg step 2 accepts absentDeprecationpresent as@<unix seconds>(from the tag)^@[0-9]+$; D1'srouteDeprecationIsReportedOncePerRoutereports a present valueasUserclientconflictscalls, 5 each of the others, 3 reports); leg step 3 (live)impact-reportrefused (non-2xx, never pinned to 500) and still reported@Deprecatedon all eight methods, plainly (nosince, noforRemoval), none on the override writeseveryMethodReachingTheSimulationRoutesIsDeprecated(a census over every public method by name)LEGACY_POLICY_WRITE_FROZENasLegacyPolicyWriteFrozenException, message naming the typed route, not retriedtheRetiredOverrideWritesThrowTheFrozenException; leg step 4 (live)AuthenticationException(401)Mutants
14/14 killed, each by a named test that compiles and fails (a mutant that does not compile would be INVALID; none was). Each mutant is one textual change; the targeted suite runs; the file is restored from its saved bytes.
public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque->public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesRequepublic CompletableFuture<SimulatePoliciesResponse> simulatePoliciesAsy->public CompletableFuture<SimulatePoliciesResponse> simulatePoliciesAsypublic ImpactReportResponse getPolicyImpactReport(ImpactReportRequest->public ImpactReportResponse getPolicyImpactReport(ImpactReportRequestpublic CompletableFuture<ImpactReportResponse> getPolicyImpactReportAs->public CompletableFuture<ImpactReportResponse> getPolicyImpactReportAspublic PolicyConflictResponse detectPolicyConflicts() {->public PolicyConflictResponse detectPolicyConflicts() {public PolicyConflictResponse detectPolicyConflicts(String policyId) {->public PolicyConflictResponse detectPolicyConflicts(String policyId) {public CompletableFuture<PolicyConflictResponse> detectPolicyConflicts->public CompletableFuture<PolicyConflictResponse> detectPolicyConflictspublic CompletableFuture<PolicyConflictResponse> detectPolicyConflicts->public CompletableFuture<PolicyConflictResponse> detectPolicyConflictspublic SimulatePoliciesResponse simulatePolicies(SimulatePoliciesReque->public SimulatePoliciesResponse simulatePolicies(SimulatePoliciesRequepublic PolicyConflictResponse detectPolicyConflicts(String policyId) {->public PolicyConflictResponse detectPolicyConflicts(String policyId) {(template != null ? template.path : request.url().encodedPath())->request.url().encodedPath()return request.newBuilder().tag(RouteTemplate.class, new RouteTemplate->return request;"/api/v1/static-policies/{id}/versions"->"/api/v1/static-policies/{id}""/api/v1/static-policies/{id}")->buildPatchRequest("/api/v1/static-policies/" + policyId, body)Live stack
Production posture (Enterprise licence, application database role), enterprise
6edf47aaf115f9eb2e07b6478305acbcdb8d24fb, the leg run at SDKccc545139.Raw responses (curl, the leg's credentials):
The leg (
runtime-e2e/v11_deprecations/run.sh), verbatim:Teardown:
The stack ran at
ccc545139; this headc0f56a6b5differs from it only in comments (master's ruling). The one change is the measured refusal body quoted increatePolicyOverride's Javadoc. The runtime leg and every test are byte-identical.git diff --stat ccc545139 c0f56a6b5:A script over every diff hunk:
Local round
Every
pull_requestworkflow's steps, run locally atc0f56a6b5, plus DCO and new-code coverage.ALL GATES PASSED.R3
Two rounds, each by an independent general-purpose agent reading the committed tree through git, per
MASTER_TRACKER_PLAYBOOK.md§"Master's R3 review protocol".Round 1 (at
dc0b721): NEEDS-CHANGES, text only; the mechanism, the tests and the leg were sound.policy_simulation_handler.go~:140-175 callsEvaluateDynamicPolicies; PRD v11 §1 items 2 and 10)/api/v1/typed-policies, which ships with the v11 series": no such route exists on enterprise maintypedPolicies(), as the other two do@Deprecatedin this releaseisPublicfilter removedPolicySimulationTest@SuppressWarnings("deprecation")on the classRound 2 (at
8625055, confirmed at8108239): SHIP-READY. All eight round-1 findings RESOLVED with file:line; the tag survives the retry executor, interceptors and the auth builder, and OkHttp 4.12.0 has the typedRequest.tag(Class). Its own nits, all folded in: the route's template form documented inPlatformRouteDeprecationandonRouteDeprecationand the README; the CHANGELOG's "now reported once" removed, because per-id reporting never shipped (D1's hook is itself unreleased), with the template behaviour folded into D1's Added entry; the README names only the families the SDK calls; the census comment states its blind spot (String.format,StringBuilder,HttpUrl.Builder); the prose says "keep answering"; and the leg gained a live step reading two real static policies by id and asserting one{id}report. ⭐ Highlights it recorded: the template rides on theRequestinto the single existing choke point, with no second report path and no signature change; the every-method test asserts the exact key set; the census covers the platform's full deprecated families and pins an exact count.