Playbook: add a feature
The question, in the user's words: "I want to add a new required action (a step a user must complete after login). What do I implement, and which existing classes can I copy?"
What you get at the end: the interface to implement, its methods (with overloads), every existing implementation to copy from, the matching factory interface, and a yes or no on whether a pattern you expect already exists.
Words used on this page:
- an interface is a list of methods a class promises to have;
- an implementation is a class that keeps that promise;
- a subtype is a class or interface below another one;
- an overload is one of several methods with the same name and different parameters;
- a default method is an interface method that already has a body, so a class need not write it.
The steps
1. How big is the interface?
niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider answer=count
INTERFACE org.keycloak.authentication.RequiredActionProvider: 7 methods
extends org.keycloak.provider.Provider
15 subtypes below it; ask without answer= for them
2. Its methods
niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider answer=names
methods:
evaluateTriggers(RequiredActionContext)
getMaxAuthAge()
getMaxAuthAge(KeycloakSession)
initiatedActionCanceled(KeycloakSession, AuthenticationSessionModel)
initiatedActionSupport()
processAction(RequiredActionContext)
requiredActionChallenge(RequiredActionContext)
Note the two getMaxAuthAge overloads. Four of the seven are default methods, so a new class must write only evaluateTriggers, requiredActionChallenge and processAction.
3. Existing implementations to copy
The full answer (no answer) lists the 15 subtypes with their files, and which methods each one implements:
niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionProvider
extended or implemented by (15, up to 3 levels down):
org.keycloak.authentication.requiredactions.DeleteAccount (implements RequiredActionProvider) services/.../DeleteAccount.java:52
org.keycloak.authentication.requiredactions.UpdatePassword (implements RequiredActionProvider) services/.../UpdatePassword.java:60
org.keycloak.authentication.requiredactions.VerifyEmail (implements RequiredActionProvider) services/.../VerifyEmail.java:68
...
methods implemented or overridden elsewhere (56 implementations):
This answer is large. Ask for it once, when you are choosing what to copy.
4. The factory that goes with it
niro ask get_class_structure class_fqn=org.keycloak.authentication.RequiredActionFactory answer=count
INTERFACE org.keycloak.authentication.RequiredActionFactory: 7 methods
extends org.keycloak.provider.ProviderFactory
19 subtypes below it; ask without answer= for them
5. Does the pattern you expect already exist?
answer=exists answers yes or no with a count:
niro ask code_grep pattern="implements RequiredActionProvider, RequiredActionFactory" answer=exists
yes: 12 matching lines in 12 files in the files searched so far
PARTIAL: the search stopped at its 1.5 s limit after 9653 of 11045 file(s) ...
So one class often plays both roles. "In the files searched so far" and the PARTIAL line say the count is a floor. To search the rest, call again with the continue_from the answer gives, or pass a folder such as path_pattern=services/. Until an answer comes back without PARTIAL, treat the count as "at least".
Why the answer is complete, and where it is not
- Subtypes are listed up to 3 levels down, by the
extendsandimplementsthe code declares. - Finding code by what it does ("is there already a rate limiter") is not in this release:
find_reusable_codeis off. Search by name withcode_grepandlist_types.
What grep would do instead
grep -rln "implements.*RequiredActionProvider" finds 13 files. The graph lists 15 subtypes. The two extra are VerifyUserProfile (extends UpdateProfile) and WebAuthnPasswordlessRegister (extends WebAuthnRegister): they implement the interface through a parent class, so no line in their files names it.
Cost
What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in Tokens, speed and accuracy.
Related
Playbook: change code safely, Playbook: learn a new codebase, Write code with Niro.