DOCSEARCHbyAlgolia
Submit Docs

Flipper Feature Flag Library

repository·main·Indexed 26 days ago

https://github.com/flippercloud/flipper

A performant feature flag library for Ruby and Rails that allows developers to control feature access for everyone, specific users, groups, or percentages of actors. It supports various storage adapters, including a specialized Http adapter with dynamic polling interval adjustment via HTTP headers, and provides a DSL for managing feature gates and complex expressions.

Tokens
6.3K
Snippets
17
Records
49
Agent score
87%

What's inside Flipper

  1. Run specs interactively inside the Docker container

    main

    If you need to run specs manually or explore the environment, you can log in to the container using a bash shell. Once inside, you can execute commands like bundle exec rspec directly.

    docker-compose run --rm app bash
# Once inside the container:
bundle exec rspec

  3. Control Poller Behavior via HTTP Headers

    main

    The Flipper poller responds to specific HTTP response headers to manage its lifecycle and frequency:

    • poll-interval: Sets the next polling interval in seconds. The poller enforces a minimum interval of 10 seconds. If a value below 10 is provided, the poller will log a warning and default to 10 seconds.
    • poll-shutdown: Triggers a graceful shutdown of the poller thread.

    Testing Header Responses in the Demo Server

    When running the demo server, you can type the following into the server terminal to simulate these headers:

    • Change Interval: Type a number (e.g., 20) to update the polling frequency.
    • Invalid Interval: Type a number below 10 (e.g., 5) to observe minimum enforcement.
    • Shutdown: Type shutdown to stop the poller.
    • Reset: Type reset to stop sending special headers and return to default behavior.

  4. Set up the development environment using Docker Compose

    main

    To minimize local tool installation requirements for different adapters, you can use Docker Compose to run the Flipper development environment. Follow these steps to build the container, install dependencies, and run tests:

    1. Install Docker Compose from https://docs.docker.com/compose/install.
    2. Build the application container: docker-compose build.
    3. Install gems: docker-compose run --rm app bundle install.
    4. Run specs: docker-compose run --rm app bundle exec rspec.
    5. Run tests: docker-compose run --rm app bundle exec rake test.
    docker-compose build
docker-compose run --rm app bundle install
docker-compose run --rm app bundle exec rspec
docker-compose run --rm app bundle exec rake test

  5. Run Flipper using Docker Compose

    main

    You can deploy the Flipper application stack using Docker Compose. The setup includes the main application container (app) and several supporting services: Redis, MongoDB, and Memcached. Note that the PostgreSQL service is currently commented out in the default configuration.

    version: "2.4"
services:
  redis:
    container_name: flipper_redis
    image: redis:6.2.5
  mongo:
    container_name: flipper_mongo
    image: mongo:4.4.8
  memcached:
    container_name: flipper_memcached
    image: memcached:1.4.33
  app:
    container_name: flipper_app
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/srv/app
    volumes_from:
      - bundle_cache
    links:
      - redis
      - mongo
      - memcached
    environment:
      - REDIS_URL=redis://redis:6379
      - MONGODB_HOST=mongo
      - MEMCACHED_URL=memcached:11211
  bundle_cache:
    container_name: flipper_bundle_cache
    image: busybox
    volumes:
      - /bundle_cache

  6. Use the Flipper CLI

    main

    The Flipper CLI allows you to manage feature flags from your terminal. By default, it attempts to load your Rails environment from ./config/environment. You can override this path using the -r flag or the FLIPPER_REQUIRE environment variable.

    Basic Usage:

    flipper <command> [options] <feature_name>

    Global Options:

    • -r PATH: The path to load your application environment (Default: ./config/environment).
    • -h, --help: Print help message.

  9. Configure Flipper with an adapter

    main

    Use Flipper.configure to set up your feature flagging configuration. The most common way to initialize Flipper is by providing an adapter via the config.adapter block. This yields a Flipper::Configuration instance.

    Flipper.configure do |config|
  config.adapter { ... }
end

  10. Configure Flipper Cloud token via generator

    main

    You can automatically configure your Flipper Cloud personal environment token during the setup process using the --token (or -t) option.

    If a token is provided, the generator will attempt to add it to your project in the following order of priority:

    1. Dotenv files: It searches for .env.development, .env.local, or .env (in order) and appends FLIPPER_CLOUD_TOKEN=<token> to the first one it finds.
    2. Rails Credentials: If no dotenv file is found and config/credentials.yml.enc exists, it injects the token into your encrypted credentials under the flipper: key.

  11. Run the Poll Interval Dynamic Adjustment Demo

    main

    This demo demonstrates how the Flipper poller dynamically adjusts its polling frequency using the poll-interval header and how it responds to the poll-shutdown header. To run the demo, you need a server to provide headers and a client to poll that server.

    Prerequisites

    Ensure you have bundle installed and the environment is set up for Ruby.

    Execution Steps

    1. Start the Server: Open a terminal and run the server script. The server listens on http://localhost:3000 and provides an interactive prompt to control headers.
    2. Start the Client: Open a second terminal and run the client script. The client starts with a default minimum interval of 10 seconds.
    # Terminal 1: Start the Server
bundle exec ruby examples/cloud/poll_interval/server.rb

# Terminal 2: Start the Client
bundle exec ruby examples/cloud/poll_interval/client.rb

  12. Enable features for different targets

    main

    All features are disabled by default. Use the following methods to enable them for different scopes:

    • Everyone: Flipper.enable :feature_name
    • Specific Actor: Flipper.enable_actor :feature_name, actor
    • Group of Actors: Flipper.enable_group :feature_name, :group_name
    • Percentage of Actors: Flipper.enable_percentage_of_actors :feature_name, percentage (where percentage is an integer)
    # Enable a feature for everyone
Flipper.enable :search

# Enable a feature for a specific actor
Flipper.enable_actor :search, current_user

# Enable a feature for a group of actors
Flipper.enable_group :search, :admin

# Enable a feature for a percentage of actors
Flipper.enable_percentage_of_actors :search, 2