risingwave_license/
feature.rs

1// Copyright 2025 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![allow(clippy::doc_markdown)]
16
17use strum::{EnumMessage, VariantArray};
18use thiserror::Error;
19
20use super::{LicenseError, LicenseManager, report_telemetry};
21
22// Define all features that require a license to use.
23//
24// # Define a new feature
25//
26// To add a new feature, add a new entry at the END of `feature.json`, following the same pattern
27// as the existing ones.
28//
29// # Check the availability of a feature
30//
31// To check the availability of a feature during runtime, call the method
32// [`check_available`](Feature::check_available) on the feature. If the feature is not available,
33// an error of type [`FeatureNotAvailable`] will be returned and you should handle it properly,
34// generally by returning an error to the user.
35//
36// # Feature availability in tests
37//
38// In tests with `debug_assertions` enabled, a special license key with all features enabled is set by
39// default. To test the behavior when a feature is not available, you can manually set a license key.
40// Check the e2e test cases under `error_ui` for examples.
41typify::import_types!(
42    schema = "src/feature.json",
43    derives = [
44        strum::VariantArray,
45        strum::IntoStaticStr,
46        strum::EnumMessage,
47    ],
48);
49
50impl Feature {
51    /// Name of the feature.
52    pub fn name(self) -> &'static str {
53        self.into()
54    }
55
56    /// Description of the feature.
57    pub fn description(self) -> &'static str {
58        self.get_documentation().unwrap_or_default()
59    }
60
61    /// Get a slice of all features.
62    pub fn all() -> &'static [Feature] {
63        Feature::VARIANTS
64    }
65
66    /// Get a slice of all features available as of 2.5 (before we introduce custom tier).
67    pub(crate) fn all_as_of_2_5() -> &'static [Feature] {
68        // `IcebergCompaction` was the last feature introduced.
69        &Feature::all()[..=Feature::IcebergCompaction as usize]
70    }
71}
72
73/// The error type for feature not available due to license.
74#[derive(Debug, Error)]
75pub enum FeatureNotAvailable {
76    // TODO(license): refine error message to include tier name & better instructions
77    #[error(
78        "feature {feature:?} is not available based on your license\n\n\
79        Hint: You may want to set a license key with `ALTER SYSTEM SET license_key = '...';` command."
80    )]
81    NotAvailable { feature: Feature },
82
83    #[error("feature {feature:?} is not available due to license error")]
84    LicenseError {
85        feature: Feature,
86        source: LicenseError,
87    },
88}
89
90impl Feature {
91    /// Check whether the feature is available based on the given license manager.
92    pub(crate) fn check_available_with(
93        self,
94        manager: &LicenseManager,
95    ) -> Result<(), FeatureNotAvailable> {
96        let check_res = match manager.license() {
97            Ok(license) => {
98                if license.tier.available_features().any(|x| x == self) {
99                    Ok(())
100                } else {
101                    Err(FeatureNotAvailable::NotAvailable { feature: self })
102                }
103            }
104            Err(error) => Err(FeatureNotAvailable::LicenseError {
105                feature: self,
106                source: error,
107            }),
108        };
109
110        report_telemetry(&self, self.name(), check_res.is_ok());
111
112        check_res
113    }
114
115    /// Check whether the feature is available based on the current license.
116    pub fn check_available(self) -> Result<(), FeatureNotAvailable> {
117        self.check_available_with(LicenseManager::get())
118    }
119}
risingwave_license/feature.rs

risingwave_license/
feature.rs
