Feature Flags & Plugin System
Relevant source files
The following files were used as context for generating this wiki page:
The Feature Flags and Plugin System in Hoop provide a robust mechanism for experimental code gating and extensible resource configuration. Feature flags enable per-organization toggles for experimental or beta functionality, ensuring that new features can be merged into the main branch safely while remaining disabled by default. The plugin system allows for the creation and management of modular resources that can be associated with specific connections to extend gateway functionality.
Sources: DEV.md:214-216, client/cmd/admin/create-plugin.go:34-36
Feature Flag System
Hoop utilizes a centralized feature flag catalog that governs the availability of experimental features across the Gateway and Agent components. Flags are defined with specific stability levels (Experimental or Beta) and are broadcasted from the gateway to connected agents in real-time via gRPC.
Architecture and Data Flow
The feature flag system is built on a per-organization basis. When an administrator enables a flag in the UI, the change is persisted to the database and updated in the gateway cache.
The diagram shows how a feature flag toggle flows from the admin interface through the database to the gateway cache, eventually reaching agents via gRPC.
Sources: DEV.md:218-223, DEV.md:251-252
Configuration and Gating
Flags are added to a central catalog located in common/featureflag/featureflag.go. Every experimental pull request must gate its behavior using the IsEnabled function.
| Field | Description |
|---|---|
Name | Unique identifier (e.g., experimental.my_feature) |
Description | Short text shown to organization admins |
Default | Boolean value (usually false) |
Stability | StabilityExperimental or StabilityBeta |
Components | List including ComponentGateway and/or ComponentAgent |
Sources: DEV.md:221-230, DEV.md:246-248
Implementation Example
// Gateway check
import "github.com/hoophq/hoop/common/featureflag"
if featureflag.IsEnabled(orgID, "experimental.my_feature") {
// Execute new path
}
Sources: DEV.md:235-239
Plugin System
The plugin system allows administrators to create "Plugin Resources" that enhance or modify the behavior of connections. Plugins are managed via the CLI or API and can be configured with environment variables and specific connection associations.
Plugin Component Structure
Plugins consist of a name, priority level, source, and configuration. The priority determines the order of execution, with higher values executing first.
This diagram illustrates the relationship between a plugin, its configuration environment variables, and the connections it is associated with.
Sources: client/cmd/admin/create-plugin.go:20-24, client/cmd/admin/create-plugin.go:78-83
Plugin Management via CLI
The CLI provides commands to create or overwrite plugins. It supports raw values, file paths, or base64 strings for configuration.
- Create/Update:
hoop admin create plugin NAME --source <org/plugin> --config key=val --connection <conn>:<config> - Overwrite Flag: Using
--overwritewill switch the HTTP method fromPOSTtoPUTif the plugin already exists.
Sources: client/cmd/admin/create-plugin.go:42-55, client/cmd/admin/create-plugin.go:121-125
Integration with UI and Rulepacks
Feature flags are also used to gate entire UI sections, such as the Rulepacks feature. Rulepacks act as bundles for configurations, including data masking and guardrails, that can be applied to multiple connections simultaneously.
UI Gating Logic
The web application checks the feature_flags object in the /serverinfo response to determine whether to render specific routes or components.
The sequence shows the web application fetching server information to check feature flag status before rendering gated features.
Sources: DEV.md:241-242, webapp_v2/src/pages/Rulepacks/index.jsx:132-138
Summary
The combination of Feature Flags and the Plugin System provides the architectural flexibility to iterate on the project safely. Feature flags manage the lifecycle of code from experimental stages to beta and general availability, while plugins offer a structured way to extend the gateway's capabilities at the resource level. Both systems are tightly integrated into the project's gRPC broadcasting mechanism and the administrative UI for seamless management.
Sources: DEV.md:214-216, DEV.md:251-252, client/cmd/admin/create-plugin.go:34-36