refactor(governance): extract query logic into openmeter/governance service

Move the governance access-query orchestration out of the v3 HTTP handler
into a new openmeter/governance service that composes the customer,
entitlement, and feature services (no persistence of its own) — mirroring
the customerbalance facade/service pattern.

The service returns domain types (CustomerAccess, FeatureAccess, QueryError,
paged QueryResult); the handler now only decodes the request, validates and
decodes cursors, calls the service, and maps the domain result to api.* types.
Service tests (Postgres-backed) move to the new package alongside the
entitlement→access mapping unit tests.

Wired idiomatically via app/common (NewGovernanceService + wire set) threaded
through router.Config → cmd/server → openmeter/server → api/v3/server Config.

Author: gergely-kurucz-konghq

api/v3/handlers/governance/handler.go

@@ -3,9 +3,7 @@ package governance
 import (
 	"context"
 
-	"github.com/openmeterio/openmeter/openmeter/customer"
-	"github.com/openmeterio/openmeter/openmeter/entitlement"
-	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/openmeter/governance"
 	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
 )
 
@@ -14,25 +12,19 @@ type Handler interface {
 }
 
 type handler struct {
-	resolveNamespace   func(ctx context.Context) (string, error)
-	customerService    customer.Service
-	entitlementService entitlement.Service
-	featureConnector   feature.FeatureConnector
-	options            []httptransport.HandlerOption
+	resolveNamespace  func(ctx context.Context) (string, error)
+	governanceService governance.Service
+	options           []httptransport.HandlerOption
 }
 
 func New(
 	resolveNamespace func(ctx context.Context) (string, error),
-	customerService customer.Service,
-	entitlementService entitlement.Service,
-	featureConnector feature.FeatureConnector,
+	governanceService governance.Service,
 	options ...httptransport.HandlerOption,
 ) Handler {
 	return &handler{
-		resolveNamespace:   resolveNamespace,
-		customerService:    customerService,
-		entitlementService: entitlementService,
-		featureConnector:   featureConnector,
-		options:            options,
+		resolveNamespace:  resolveNamespace,
+		governanceService: governanceService,
+		options:           options,
 	}
 }

api/v3/handlers/governance/mapping.go

@@ -1,61 +1,104 @@
 package governance
 
 import (
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
 	api "github.com/openmeterio/openmeter/api/v3"
-	"github.com/openmeterio/openmeter/openmeter/entitlement"
-	booleanentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/boolean"
-	meteredentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/metered"
-	staticentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/static"
+	customershandler "github.com/openmeterio/openmeter/api/v3/handlers/customers"
+	"github.com/openmeterio/openmeter/openmeter/governance"
 )
 
-// mapEntitlementToAccess converts an entitlement value to a governance feature access result.
-// When has_access is false, the reason code is derived from the entitlement type.
-func mapEntitlementToAccess(v entitlement.EntitlementValue) api.GovernanceFeatureAccess {
-	switch ent := v.(type) {
-	case *meteredentitlement.MeteredEntitlementValue:
-		if ent.HasAccess() {
-			return api.GovernanceFeatureAccess{HasAccess: true}
-		}
-		return api.GovernanceFeatureAccess{
-			HasAccess: false,
-			Reason: &api.GovernanceFeatureAccessReason{
-				Code:    api.GovernanceFeatureAccessReasonCodeUsageLimitReached,
-				Message: "usage limit for feature reached",
-			},
+// ToAPIGovernanceQueryResponse maps a domain QueryResult to the API response.
+func ToAPIGovernanceQueryResponse(res governance.QueryResult, pageSize int) api.GovernanceQueryResponse {
+	data := make([]api.GovernanceQueryResult, 0, len(res.Customers))
+	for _, c := range res.Customers {
+		features := make(map[string]api.GovernanceFeatureAccess, len(c.Features))
+		for key, fa := range c.Features {
+			features[key] = toAPIFeatureAccess(fa)
 		}
 
-	case *booleanentitlement.BooleanEntitlementValue:
-		if ent.HasAccess() {
-			return api.GovernanceFeatureAccess{HasAccess: true}
-		}
-		return api.GovernanceFeatureAccess{
-			HasAccess: false,
-			Reason: &api.GovernanceFeatureAccessReason{
-				Code:    api.GovernanceFeatureAccessReasonCodeFeatureUnavailable,
-				Message: "feature is not available for customer",
-			},
-		}
+		data = append(data, api.GovernanceQueryResult{
+			Matched:   c.Matched,
+			Customer:  customershandler.ToAPIBillingCustomer(c.Customer),
+			Features:  features,
+			UpdatedAt: c.UpdatedAt,
+		})
+	}
 
-	case *staticentitlement.StaticEntitlementValue:
-		if ent.HasAccess() {
-			return api.GovernanceFeatureAccess{HasAccess: true}
-		}
-		return api.GovernanceFeatureAccess{
-			HasAccess: false,
-			Reason: &api.GovernanceFeatureAccessReason{
-				Code:    api.GovernanceFeatureAccessReasonCodeFeatureUnavailable,
-				Message: "feature is not available for customer",
-			},
+	errs := make([]api.GovernanceQueryError, 0, len(res.Errors))
+	for _, e := range res.Errors {
+		errs = append(errs, api.GovernanceQueryError{
+			Customer: lo.ToPtr(e.CustomerKey),
+			Code:     toAPIQueryErrorCode(e.Code),
+			Message:  e.Message,
+		})
+	}
+
+	return api.GovernanceQueryResponse{
+		Data:   data,
+		Errors: errs,
+		Meta:   toAPICursorMeta(res, pageSize),
+	}
+}
+
+func toAPIFeatureAccess(fa governance.FeatureAccess) api.GovernanceFeatureAccess {
+	out := api.GovernanceFeatureAccess{HasAccess: fa.HasAccess}
+	if fa.Reason != nil {
+		out.Reason = &api.GovernanceFeatureAccessReason{
+			Code:    toAPIReasonCode(fa.Reason.Code),
+			Message: fa.Reason.Message,
 		}
+	}
+	return out
+}
 
+func toAPIReasonCode(code governance.ReasonCode) api.GovernanceFeatureAccessReasonCode {
+	switch code {
+	case governance.ReasonUsageLimitReached:
+		return api.GovernanceFeatureAccessReasonCodeUsageLimitReached
+	case governance.ReasonFeatureUnavailable:
+		return api.GovernanceFeatureAccessReasonCodeFeatureUnavailable
+	case governance.ReasonFeatureNotFound:
+		return api.GovernanceFeatureAccessReasonCodeFeatureNotFound
+	case governance.ReasonNoCreditAvailable:
+		return api.GovernanceFeatureAccessReasonCodeNoCreditAvailable
 	default:
-		// NoAccessValue or unknown type
-		return api.GovernanceFeatureAccess{
-			HasAccess: false,
-			Reason: &api.GovernanceFeatureAccessReason{
-				Code:    api.GovernanceFeatureAccessReasonCodeFeatureUnavailable,
-				Message: "feature is not available for customer",
-			},
+		return api.GovernanceFeatureAccessReasonCodeUnknown
+	}
+}
+
+func toAPIQueryErrorCode(code governance.QueryErrorCode) api.GovernanceQueryErrorCode {
+	switch code {
+	case governance.QueryErrorCustomerNotFound:
+		return api.GovernanceQueryErrorCodeCustomerNotFound
+	default:
+		return api.GovernanceQueryErrorCodeUnknown
+	}
+}
+
+// toAPICursorMeta builds cursor pagination metadata from the domain result.
+func toAPICursorMeta(res governance.QueryResult, pageSize int) api.CursorMeta {
+	meta := api.CursorMeta{
+		Page: api.CursorMetaPage{
+			Next:     nullable.NewNullNullable[string](),
+			Previous: nullable.NewNullNullable[string](),
+			Size:     float32(pageSize),
+		},
+	}
+
+	if res.First != nil {
+		meta.Page.First = lo.ToPtr(res.First.Encode())
+		if res.HasPrev {
+			meta.Page.Previous = nullable.NewNullableWithValue(res.First.Encode())
 		}
 	}
+	if res.Last != nil {
+		meta.Page.Last = lo.ToPtr(res.Last.Encode())
+		if res.HasNext {
+			meta.Page.Next = nullable.NewNullableWithValue(res.Last.Encode())
+		}
+	}
+
+	return meta
 }