# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `flags` | `key` (primary key), `description`, `enabled`, `client_visible`, `rules` (JSON), `last_asked_at`, `created_at`, `deleted_at` | | `flag_overrides` | `flag_key`, `subject_id`, `value`; primary key on the first two | | `flag_changes` | `id`, `flag_key`, `actor_id`, `before` (JSON), `after` (JSON), `at` (only if `change_history` is on) | A deleted flag keeps its row with `deleted_at` set, so its key cannot be reused. The subject is a user or a workspace, as the `subject` input says. Its id is turned to text before it is used below. ## Rules as data ```json [ { "when": [{ "attribute": "email", "op": "ends_with", "value": "@example.com" }], "then": "on" }, { "when": [{ "attribute": "plan", "op": "in", "value": ["pro", "team"] }], "then": { "percentage": 20 } }, { "when": [], "then": "off" } ] ``` ## The bucket ``` text = flag key, a colon, subject id for example new-editor:user_1 digest = SHA-256 of text as UTF-8 number = the first 4 bytes of digest, read as an unsigned big-endian integer bucket = number modulo 10000 ``` The flag is on when `bucket < percentage * 100`. Do the comparison in whole numbers: 12.5% is 1250. | Flag key | Subject id | Bucket | On at 20% | On at 60% | | --- | --- | --- | --- | --- | | `new-editor` | `user_1` | 5258 | no | yes | | `new-editor` | `user_2` | 8497 | no | no | | `new-editor` | `user_3` | 6249 | no | no | | `new-editor` | `user_4` | 1707 | yes | yes | | `dark-mode` | `user_1` | 2089 | no | yes | Over the 10,000 subject ids `user_1` to `user_10000`: | Rollout | Subjects with the flag on | | --- | --- | | `new-editor` at 20% | 1,979 | | `new-editor` at 50% | 4,970 | | `new-editor` at 20% and `dark-mode` at 20%, both on | 409 | ## Order of evaluation 1. No flag with that key: off. 2. `enabled` is off: off. 3. An override for the subject: its value. 4. The first rule whose conditions all hold: its outcome. 5. Otherwise: off. Return the answer with the reason, one of `unknown`, `killed`, `override`, `rule` with its position, or `default`. "Check a subject" shows the reason. ## Caching - Keep every flag and override in memory, loaded in one query each, and reload when they are older than `cache_seconds`. - Reload in the background. A request never waits for a reload after the first. - Write `last_asked_at` at most once an hour per flag, from a background task. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## Named here - A rule's position in a reason is counted from 1. - In the form, the values of an `in` rule are separated by commas. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.