Repository navigation
docs(examples): v11 examples and the platform notes - #245
Merged
Merged
Conversation
Two runnable examples for the v11 platform, each a Maven project that Examples Compile builds: examples/pep-handshake declares an enforcement point's capabilities and decides with them, printing each verdict and its reasons; examples/typed-policies reads what the deployment may author, validates a document and, with AXONFLOW_TYPED_POLICY_PUBLISH=1, publishes and activates it. The README runs the handshake example first, because a decide after an organization-scope constraint is activated is denied fail-closed with reasons ["unknown_constraint"] unless it supplies the attribute. The README gains a v11.0.0 platform section with the platform minimum of each chapter: the PEP capability handshake is read from v10.4.0, and typed authoring, decision provenance, the deprecation stamps and the write freeze need v11.0.0. The handshake's docs no longer say a client that declares nothing is treated as before: from v11.0.0 a decide under an organization's redact override refuses a caller that does not declare redaction. The typed authoring docs name the per-policy override retirement (agent-api's PerPolicyOverrideRetired response). The runtime leg v11_examples builds both examples against this tree and runs them on a live Community stack in the README's order: the fresh decide is allowed and the refused declaration fails in the client at /pep_id; the document is published and activated; the decide after the activation is printed as an observation of the by-design deny. 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
The Java half of the SDK train's D5, mirroring getaxonflow/axonflow-sdk-go#234 (
c921833be) as amended: two runnable examples for the v11 platform, a README section with each chapter's platform minimum, the three corrections to D2's docs, and a CHANGELOG preamble for the release that carries the train. No version number and no version bump; the release is cut separately.Part of getaxonflow/axonflow-enterprise#3746.
What changes
examples/pep-handshakedeclares an enforcement point's capabilities withPEPHandshake.of(...), decides with the client's declaration and with a client derived bywithPEPHandshake(...), printing each verdict and its reasons, and shows a declaration the platform would refuse failing in the client at/pep_id.examples/typed-policiesreads what the deployment may author, validates a document and prints every finding, publishes and activates it whenAXONFLOW_TYPED_POLICY_PUBLISH=1(a refusal prints the platform's reason and findings), and shows the document in force.examples/*/pom.xml), useAXONFLOW_AGENT_URL,AXONFLOW_CLIENT_IDandAXONFLOW_CLIENT_SECRETas the existing examples do, exit non-zero on a failed step, and carry the sentence: "after a document with an organization-scope constraint is activated, a decide that does not supply the attribute the constraint conditions on is denied fail-closed with reasons ["unknown_constraint"]; supply the attribute or run this example on a fresh stack". The README runs the handshake example before the typed-policies one.2ad7091):CHANGELOG.md:32called it "the v11.0.0 PEP capability handshake";README.md:396andPEPHandshake.java:38-39said a client that declares nothing is treated "as it did before the handshake existed". The handshake is read from v10.4.0 (measured by W3-P at tagb10d07061: every plane callsresolveAndRecordPEPHandshakeOnce), and from v11.0.0 a decide under an organization's redact override refuses a caller that does not declare redaction, on both editions. The README heading is now "PEP capability handshake (v10.4.0+)".createPolicyOverrideanddeletePolicyOverrideanswer 409LEGACY_POLICY_WRITE_FROZEN(agent-api'sPerPolicyOverrideRetiredresponse, since getaxonflow/axonflow-enterprise#4221), and a system control is changed in the organization's typed document, in itssystem_controlssection.[Unreleased], with no version number: "The first Java SDK release carrying these entries sends the PEP capability handshake, which a platform reads from v10.4.0, and reaches /api/v1/typed-policies, which needs a v11.0.0 platform; against an older platform it works unchanged. Upgrade the SDK before the platform: from v11.0.0, Decide under an organization's redact override refuses a caller that does not declare redaction, and only a release that sends the handshake can declare it." Plus an Added bullet for the examples.runtime-e2e/v11_examplesbuilds both examples against this tree and runs them on a live stack in the README's order (below). The runtime-e2e gate's escape hatch is not used: the examples are user-facing, so they get a leg.Brief corrections (ruled by master)
examples/pep-handshakeandexamples/typed-policies, the repository's hyphenated convention (explain-decision,list-decisions), not the brief's Go-stylepep_handshake/typed_policies.definition-of-done.yml's required "Runtime E2E required for user-facing changes" countsexamples/as user-facing, and the escape hatch is not used on a Java PR.Live stack
Community on the application database role (probe: all main pools on
axonflow_app_role), enterprise6edf47aaf115f9eb2e07b6478305acbcdb8d24fb, SDK19b255432, a fresh stack.The leg (
runtime-e2e/v11_examples/run.sh), verbatim. Steps 1 and 2 are asserted; step 3 is the observation the examples' sentence describes (observed: verdict=deny reasons=[unknown_constraint] obligations=0), printed and not pinned, whose missing policy provenance is getaxonflow/axonflow-enterprise#4227:Teardown:
Local round
Every
pull_requestworkflow's steps, run locally at19b255432, plus DCO.ALL GATES PASSED.examples/pep-handshakeandexamples/typed-policiesR3
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
376fb7c): NEEDS-CHANGES.decidesends theDecideRequestas built (AxonFlow.javahas nocaller_identity;DecideRequestisNON_NULLwith the identity null by default), and the mergedruntime-e2e/pep_handshake_planesruns decide on Community with credentialscommunity)typed-policiesexited 0 after a refused publishnilis an item on sdk-go #236slf4j-simplebinding the other legs usemvn -q -DskipTests installstill runs the unit suite in this pom-DskipTests -DskipUnitTests=truein both examples and the README, including its existing lineRound 2 (at
bde0252c1, confirmed at30efc6ad5): SHIP-READY. F1-F8 RESOLVED with file:line, and F1 verified on the wire (decision_handler.go:955-968compares the body's organization only when it is set). Its three nits, folded in: two older Javadocs (PEPHandshakeException,PEPCapability) still dated the handshake to v11.0.0 and now say it is read from v10.4.0; both examples run through google-java-format; a README comment aligned. It re-checked that the strings the leg greps (verdict=,refused at /pep_id:, a bareactivated) are unchanged.Traps met while verifying
heavy-slotticket: targetedmvn test -Dtest=...runs, formatter runs,javaccompile-checks withmvn compile dependency:build-classpath, onemvn javadoc:javadoc, and themvn compilein the rebase script. The habit was that a targeted run needs no slot. None overlapped this change's own round, but on a shared machine they were load the semaphore could not see. Every compile and Maven run now takes a ticket.heavy-slot: slot2 -> w3q-d5-gates (run, ...)). The tree, the local Maven repository's9.3.0copy and the process table were checked clean after the kill. The round in this body is the full re-run at the same head, not a stitched one.