# Feature flags ## What this builds Switches that turn parts of an app on for some people and off for others without a deploy. A flag has rules, can be rolled out to a percentage, and can be killed at once. App code asks one function whether a flag is on. Read `spekkr.inputs.json` first. A rollout counts the thing named by `subject`. Flags are cached for `cache_seconds` seconds. `change_history` decides whether R6 exists and `client_endpoint` whether R7 does. This spec needs the app to know who is signed in and who is an administrator. It does not build sign-in. ## Out of scope - Experiments, metrics and deciding which variant won. - Flags with values other than on and off. - Separate settings per environment. Each environment has its own database. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Flags - A flag has a key of lowercase letters, digits and hyphens, a description, and a kill switch called `enabled`. - A flag whose `enabled` is off is off for everyone, whatever its rules say. - A key cannot be changed or reused after the flag is deleted. Accept when: a flag with `enabled` off is off for a subject its rules would turn it on for, and a deleted key cannot be created again. ### R2. Rules - A flag has an ordered list of rules. The first rule whose conditions all hold decides. If none holds, the flag is off. - A condition compares one attribute of the subject: `equals`, `in` a list, or `ends_with`, which is meant for email domains. Comparison ignores case. - A rule's outcome is on, off, or a percentage from 0 to 100 with up to two decimal places. - A rule with no conditions holds for everyone. It is how "20% of everyone" is written. Accept when: rules are tried in order and the first match decides, and an attribute that the subject does not have makes a condition false, not an error. ### R3. Percentages - A percentage is decided by the bucket in `design.md`, a number from 0 to 9999 worked out from the flag's key and the subject's id. - The flag is on when the bucket is less than the percentage times 100. - The same subject always gets the same answer for the same flag and percentage. Raising a percentage never turns the flag off for a subject who had it on. - Two flags at the same percentage do not pick the same subjects. Accept when: the table of buckets in `design.md` is reproduced exactly, and the counts given under it are reproduced exactly. ### R4. Ask whether a flag is on - App code calls `is_enabled(flag_key, subject, attributes)`. - A key that has no flag answers off, and is logged once per process. - Asking does not query the database each time. Flags are loaded together and kept for `cache_seconds` seconds. - If the database cannot be reached, the last loaded flags keep answering. If nothing was ever loaded, everything is off. Accept when: a thousand calls make at most one database query, a change shows up after the cache time, and with the database stopped the last answers stand. ### R5. Overrides - A flag can be forced on or off for single subjects by id. An override beats every rule, but not the kill switch. Accept when: an override to on wins over a rule that says off, and loses to `enabled` off. ### R6. History Only if `change_history` is on. - Every change to a flag, its rules or its overrides records who made it, when, and the flag as it was before and after. - The flag's page shows its history, newest first. - History is never edited. It is deleted only with the flag, after 90 days. Accept when: each kind of change leaves one entry with the right before and after. ### R7. Flags for the browser Only if `client_endpoint` is on. - `GET /api/flags` answers a signed-in browser with the flags marked "visible to the browser", each as on or off for that subject. - The answer never contains rules, percentages, overrides or flags not so marked. Accept when: the answer for two subjects differs where their rules differ, and a flag that is not marked visible never appears. ### R8. Pages for administrators - A list of flags with their state, the percentage if there is one, and when each was last asked about. Flags not asked about for 30 days are marked stale. - A flag's page to edit the description, the kill switch, the rules, their order and the overrides. - "Check a subject": enter an id and attributes, and see the answer and which rule gave it. - Only administrators reach these pages. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen, and a person who is not an administrator gets 403. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - A README explains how to add a flag, how to ask about it from code, and how to run the tests.