Repository navigation
feat(reconcile): add BillingFeature kind #2046
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
rohilsurana
wants to merge
6
commits into
main
Choose a base branch
from
feat/pricing-feature-hover-info
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
3dfba45
feat(reconcile): add BillingFeature spec and diff
rohilsurana dabb36c
feat(reconcile): add BillingFeature reconciler
rohilsurana 1446ede
feat(reconcile): add BillingFeature export
rohilsurana 787e3d9
feat(reconcile): require BillingFeature before BillingProduct in a file
rohilsurana f50640c
feat(cli): register BillingFeature reconcile kind
rohilsurana 662c0b3
docs(reconcile): document BillingFeature kind
rohilsurana File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
58 changes: 58 additions & 0 deletions
58
docs/rfcs/0001-declarative-reconcile-addendum-billingfeature.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # RFC 0001 addendum: the BillingFeature kind | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Status** | Accepted. Implemented in the `reconcile` package and the `reconcile` and `export` commands. | | ||
| | **Author** | Rohil Surana | | ||
| | **Created** | 2026-11-07 | | ||
| | **Updated** | 2026-11-07 | | ||
| | **Extends** | [RFC 0001: Declarative management of platform resources](0001-declarative-reconcile.md) | | ||
|
|
||
| ## Summary | ||
|
|
||
| This addendum adds one kind, BillingFeature, to the kinds in RFC 0001. It follows the five | ||
| rules of RFC 0001. RFC 0001 itself is not changed. | ||
|
|
||
| Before this kind, a file could only name a feature inside a BillingProduct. A feature's title | ||
| and metadata could not be set from a file. They lived only in the database. BillingFeature lets | ||
| a file set them, so a UI can show a feature's title and a tooltip from its metadata. | ||
|
|
||
| ## Where it fits | ||
|
|
||
| | Kind | Object or value | Identity | A missing entry | How to remove | | ||
| |---|---|---|---|---| | ||
| | BillingFeature | object | name | plan fails | cannot be removed | | ||
|
|
||
| BillingFeature is an object, like BillingProduct and BillingPlan. Every feature on the server | ||
| must be in the file, and a missing one fails the plan. | ||
|
|
||
| A feature cannot be deleted or retired. There is no delete API and no inactive state. So | ||
| `delete: true` is rejected, and a feature must stay in the file for as long as it exists on the | ||
| server. `frontier export billingfeature` lists every feature, so a file can start from it. | ||
|
|
||
| ## The kind | ||
|
|
||
| An entry is a feature `{name, title, metadata}`. | ||
|
|
||
| - **Name.** The name is the identity. It is matched exactly as the server stores it, including | ||
| case and spaces. Two server features whose names differ only by case are two entries. A file | ||
| name that matches a server feature only by case fails the plan, so a typo is not created as a | ||
| new feature. A name made only of spaces is rejected. | ||
| - **Title and metadata.** Both follow rule 2. An omitted title is empty. Omitted metadata is | ||
| `{}`. Metadata is one whole map: a file that drops a key removes it. | ||
| - **Product links.** Product links are owned by the BillingProduct kind. An update keeps the | ||
| current links, and export never writes them. A new feature is created with no links. | ||
| - **Order.** In one file, BillingFeature must come before BillingProduct, because a product | ||
| lists features by name. | ||
| - **Out of scope.** A feature with a name shorter than three characters cannot be sent through | ||
| the API, so it is left out of the plan and the export. | ||
|
|
||
| ## Server-side change | ||
|
|
||
| Rule 2 needs every default to be reachable through the API. Before this change, `UpdateFeature` | ||
| kept the old title and metadata when the request sent them empty. Now `UpdateFeature` writes the | ||
| title, metadata and product links exactly as sent, and finds the feature by name. Other paths | ||
| that save features, like creating a product or a plan, keep their old merge behavior. | ||
|
|
||
| The CLI and the server are expected to run the same version. An older server keeps the old | ||
| values when a file clears them, and the plan keeps showing the same update. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,157 @@ | ||
| package reconcile | ||
|
|
||
| import ( | ||
| "encoding/json" | ||
| "fmt" | ||
| "sort" | ||
| "strings" | ||
|
|
||
| "google.golang.org/protobuf/types/known/structpb" | ||
| ) | ||
|
|
||
| const KindBillingFeature = "BillingFeature" | ||
|
|
||
| type BillingFeatureSpec struct { | ||
| Name string `yaml:"name"` | ||
| Title string `yaml:"title,omitempty"` | ||
| Metadata map[string]any `yaml:"metadata,omitempty"` | ||
| Delete bool `yaml:"delete,omitempty"` | ||
| } | ||
|
|
||
| type currentBillingFeature struct { | ||
| ID string | ||
| Name string | ||
| Title string | ||
| Metadata map[string]any | ||
| ProductIDs []string | ||
| } | ||
|
|
||
| type billingFeatureOp struct { | ||
| action opAction | ||
| spec BillingFeatureSpec | ||
| current currentBillingFeature | ||
| detail string | ||
| } | ||
|
|
||
| func (o billingFeatureOp) String() string { | ||
| if o.action == opUpdate { | ||
| return fmt.Sprintf("update feature %s (%s)", o.spec.Name, o.detail) | ||
| } | ||
| return fmt.Sprintf("add feature %s", o.spec.Name) | ||
| } | ||
|
|
||
| func validateBillingFeatureSpec(s BillingFeatureSpec) error { | ||
| if strings.TrimSpace(s.Name) == "" { | ||
| return fmt.Errorf("feature name is required") | ||
| } | ||
| if s.Delete { | ||
| return fmt.Errorf("feature %q cannot be deleted: there is no feature delete API; keep the entry in the file", s.Name) | ||
| } | ||
| if _, err := structpb.NewStruct(s.Metadata); err != nil { | ||
| return fmt.Errorf("feature %q metadata cannot be stored: %w", s.Name, err) | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
| func checkBillingFeatureSpecs(specs []BillingFeatureSpec) error { | ||
| seen := map[string]struct{}{} | ||
| for _, s := range specs { | ||
| if err := validateBillingFeatureSpec(s); err != nil { | ||
| return fmt.Errorf("invalid billing feature spec %q: %w", s.Name, err) | ||
| } | ||
| if _, dup := seen[s.Name]; dup { | ||
| return fmt.Errorf("feature %q is listed more than once", s.Name) | ||
| } | ||
| seen[s.Name] = struct{}{} | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
| func diffBillingFeatures(desired []BillingFeatureSpec, current []currentBillingFeature) ([]billingFeatureOp, error) { | ||
| if err := checkBillingFeatureSpecs(desired); err != nil { | ||
| return nil, err | ||
| } | ||
|
|
||
| byName := make(map[string]currentBillingFeature, len(current)) | ||
| byLowerName := make(map[string]currentBillingFeature, len(current)) | ||
| for _, c := range current { | ||
| byName[c.Name] = c | ||
| byLowerName[strings.ToLower(c.Name)] = c | ||
| } | ||
|
|
||
| listed := map[string]struct{}{} | ||
| var adds, updates []billingFeatureOp | ||
| for _, s := range desired { | ||
| cur, exists := byName[s.Name] | ||
| if !exists { | ||
| if other, caseOnly := byLowerName[strings.ToLower(s.Name)]; caseOnly { | ||
| return nil, fmt.Errorf("feature %q matches server feature %q only by case; feature names are case sensitive, so use the server name", s.Name, other.Name) | ||
| } | ||
| adds = append(adds, billingFeatureOp{action: opAdd, spec: s}) | ||
| continue | ||
| } | ||
| listed[cur.Name] = struct{}{} | ||
| changes, err := billingFeatureChanges(s, cur) | ||
| if err != nil { | ||
| return nil, err | ||
| } | ||
| if len(changes) > 0 { | ||
| updates = append(updates, billingFeatureOp{ | ||
| action: opUpdate, | ||
| spec: s, | ||
| current: cur, | ||
| detail: strings.Join(changes, ", "), | ||
| }) | ||
| } | ||
| } | ||
|
|
||
| var unlisted []string | ||
| for _, c := range current { | ||
| if _, ok := listed[c.Name]; !ok { | ||
| unlisted = append(unlisted, c.Name) | ||
| } | ||
| } | ||
| if len(unlisted) > 0 { | ||
| sort.Strings(unlisted) | ||
| return nil, fmt.Errorf("features exist on the server but are not in the file: %s; a feature cannot be removed through the API, so add it to the file (frontier export billingfeature lists them all)", strings.Join(unlisted, ", ")) | ||
| } | ||
|
|
||
| sortBillingFeatureOpsByName(adds) | ||
| sortBillingFeatureOpsByName(updates) | ||
| return append(adds, updates...), nil | ||
| } | ||
|
|
||
| func billingFeatureChanges(s BillingFeatureSpec, cur currentBillingFeature) ([]string, error) { | ||
| var changes []string | ||
| if s.Title != cur.Title { | ||
| changes = append(changes, "title") | ||
| } | ||
| desiredMetadata, err := canonicalMetadata(s.Metadata) | ||
| if err != nil { | ||
| return nil, fmt.Errorf("feature %q desired metadata: %w", s.Name, err) | ||
| } | ||
| currentMetadata, err := canonicalMetadata(cur.Metadata) | ||
| if err != nil { | ||
| return nil, fmt.Errorf("feature %q server metadata: %w", s.Name, err) | ||
| } | ||
| if desiredMetadata != currentMetadata { | ||
| changes = append(changes, "metadata") | ||
| } | ||
| return changes, nil | ||
| } | ||
|
|
||
| func canonicalMetadata(m map[string]any) (string, error) { | ||
| asStored, err := structpb.NewStruct(m) | ||
| if err != nil { | ||
| return "", err | ||
| } | ||
| b, err := json.Marshal(asStored.AsMap()) | ||
| if err != nil { | ||
| return "", err | ||
| } | ||
| return string(b), nil | ||
| } | ||
|
|
||
| func sortBillingFeatureOpsByName(ops []billingFeatureOp) { | ||
| sort.Slice(ops, func(i, j int) bool { return ops[i].spec.Name < ops[j].spec.Name }) | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Exclude out-of-scope features from the full-list requirement.
Features with names shorter than three characters are omitted from export. If a user follows this requirement and adds one to the file, reconciliation fails. State that only in-scope features must be listed, and that short-name entries are rejected.