Agora

You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) docs

Reading Flags

ctx.flags in HTTP, the service elsewhere, evaluation details, route guards and Edge templates.

In a request: ctx.flags

async index({ flags }: HttpContext) {
  await flags.enabled('new_player')        // boolean flags
  await flags.value('max_uploads')         // the typed value
  await flags.variant('checkout')          // the variant name
  await flags.details('checkout')          // value, variant, reason, error
}

Values are memoized for the request: a flag cannot change halfway through rendering a page.

The subject is the signed-in user. With @adonis-agora/authkit-client that is the authkit identity, with no configuration, and its claims become targeting attributes:

AttributeFrom
targetingKeythe sub claim: the same person in every app
email, emailDomainthe email claim
globalRolesauthkit global roles (in matches any)
orgId, orgSlug, orgRolethe session's active organization

So "everyone in organization acme" or "users with the BETA role" are plain rules, and a rollout split by orgId gives a whole organization the same variant. Without authkit, ctx.auth.user is used. Authentication covers @adonisjs/auth, Bouncer and writing your own identity provider.

To use something else — an organization, an anonymous id — set subject in the config:

config/flags.ts
export default defineConfig({
  flags: { /* … */ },
  subject: (ctx) => ctx.auth.user ?? { id: ctx.request.cookie('anon_id'), type: 'anonymous' },
  // Targeting attributes for every subject. Read them from your own data, never from the request.
  attributes: async (subject) => {
    const user = await User.find(subject.id)
    return { plan: user?.plan, country: user?.country, orgId: user?.organizationId }
  },
})

Anywhere else: the service

import flags from '@adonis-agora/flags/services/main'

await flags.for(user).enabled('new_player')
await flags.for({ id: org.id, type: 'organization', attributes: { plan: org.plan } }).value('max_uploads')

flags.for() takes a model with an id, an id, or { id, type, attributes }.

Why did I get this value?

const details = await ctx.flags.details('checkout')
// {
//   flagKey: 'checkout',
//   value: 'one_page',
//   variant: 'one_page',
//   reason: 'TARGETING_MATCH',            // STATIC, DEFAULT, TARGETING_MATCH, SPLIT, DISABLED, ERROR
//   flagMetadata: { ruleId: 'pro-users', rulesetVersion: '42' },
// }

A flag declared in code but not configured yet serves its default with reason: 'DEFAULT' and flagMetadata.configured: false: the normal state of a new flag, not an error.

A failure never throws. It returns the code default with reason: 'ERROR' and an errorCode (FLAG_NOT_FOUND for a key nobody declared, PARSE_ERROR, TYPE_MISMATCH, TARGETING_KEY_MISSING). These names are OpenFeature's.

Route guard

start/routes.ts
import { middleware } from '#start/kernel'

router
  .get('/checkout/new', [NewCheckoutController])
  .use(middleware.flag({ flag: 'new_checkout' }))

router
  .get('/checkout/one-page', [OnePageController])
  .use(middleware.flag({ flag: 'checkout', variants: ['one_page'] }))

When the flag says no, the route answers 404, as if it did not exist. Change it with status.

Edge templates

@flag('new_player')
  @include('partials/new_player')
@else
  @include('partials/classic_player')
@end

{{-- multivariate: any of the listed variants --}}
@flag('checkout', 'one_page')
  @include('partials/one_page_checkout')
@end

The middleware also shares the request's flags as flags, for anything else:

<p>Up to {{ await flags.value('max_uploads') }} files.</p>

On this page

Partner

Your product as the official integration for Flags, right here.

Become a partner →