Implement declarative enums abstraction
What does this MR do?
Instead of duplicating the logic all around the enum types, we can use this helper method to consolidate the logic which will remove the implementation details from the type classes and finally will make them more declarative and easy to reason about.
Usage of the new DSL
The whole point of the new DSL is to provide a way to centralize the place we define Enum values and make them easier to document. To do so we should first define the enum module(SSOT) and then register it to an Active Record model. We can also easily expose the enum values on GraphQL.
Defining an enum module
module DismissalReasons
extend DeclarativeEnum
key :dismissal_reason
name 'DismissalReasonOfVulnerability'
description <<~TEXT
This enum holds the user-selected dismissal reason
when they are dismissing the vulnerabilities
TEXT
define do
acceptable_risk value: 0, description: 'The vulnerability is known but is considered to be an acceptable business risk.'
false_positive value: 1, description: 'An error in reporting the presence of a vulnerability in a system when the vulnerability is not present.'
used_in_tests value: 2, description: 'The finding is not a vulnerability because it is part of a test or is test data.'
end
end
Descriptions for the enum values are not required so you can omit them if not necessary(IMHO description is always good to have though);
module DismissalReasons
extend DeclarativeEnum
key :dismissal_reason
name 'DismissalReasonOfVulnerability'
description <<~TEXT
This enum holds the user-selected dismissal reason
when they are dismissing the vulnerabilities
TEXT
define do
acceptable_risk value: 0
false_positive value: 1
used_in_tests value: 2
end
end
EE
Extending Enum values on We can use the prepend_if_ee
helper method to extend the values of an Enum for the enterprise edition like so;
# app/enums/dismissal_reasons.rb
DismissalReasons.prepend_if_ee('EE::DismissalReasons')
# ee/app/enums/ee/dismissal_reasons.rb
module EE
module DismissalReasons
extend DeclarativeEnum
define do
not_applicable value: 3
end
end
end
This will extend the values of the DismissalReasons
enum with the ones registered on the EE::DismissalReasons
.
Registering the enum to an Active Record model;
class VulnerabilityFeedback
declarative_enum DismissalReasons
end
This will use the key
value set on the declarative enum to register the enum.
Exposing the enum values on GraphQL API;
This will expose all the values and their respective descriptions along with the name of the enum and description of the enum.
module Types
module Vulnerabilities
class DismissalReasonEnum < BaseEnum
declarative_enum DismissalReasonEnum
end
end
end
Exposing the enum values on a different channel?
By promoting the Enum values to be a first-class citizen, we can open the doors for endless opportunities. If needed, we can also add documentation helpers for Grape endpoints or deprecating the enum values, etc.
Does this MR meet the acceptance criteria?
Conformity
- [-] Changelog entry
- [-] Documentation (if required)
-
Code review guidelines -
Merge request performance guidelines -
Style guides - [-] Database guides
- [-] Separation of EE specific content
Availability and Testing
- [-] Review and add/update tests for this feature/bug. Consider all test levels. See the Test Planning Process.
- [-] Tested in all supported browsers
- [-] Informed Infrastructure department of a default or new setting change, if applicable per definition of done
Security
If this MR contains changes to processing or storing of credentials or tokens, authorization and authentication methods and other items described in the security review guidelines:
- [-] Label as security and @ mention
@gitlab-com/gl-security/appsec
- [-] The MR includes necessary changes to maintain consistency between UI, API, email, or other methods
- [-] Security reports checked/validated by a reviewer from the AppSec team