schema-agnostic approaches with working tests

Signed-off-by: Jordan <jordan@nimblewidget.com>

Author: grokspawn

cmd/catalogd/main.go

@@ -365,10 +365,25 @@ func run(ctx context.Context) error {
 		return err
 	}
 
+	var metasMode storage.MetasHandlerMode
+	if features.CatalogdFeatureGate.Enabled(features.APIV1MetasHandler) {
+		metasMode = storage.MetasHandlerEnabled
+	} else {
+		metasMode = storage.MetasHandlerDisabled
+	}
+
+	var graphqlMode storage.GraphQLQueriesMode
+	if features.CatalogdFeatureGate.Enabled(features.GraphQLCatalogQueries) {
+		graphqlMode = storage.GraphQLQueriesEnabled
+	} else {
+		graphqlMode = storage.GraphQLQueriesDisabled
+	}
+
 	localStorage = storage.NewLocalDirV1(
 		storeDir,
 		baseStorageURL,
-		features.CatalogdFeatureGate.Enabled(features.APIV1MetasHandler),
+		metasMode,
+		graphqlMode,
 	)
 
 	// Config for the catalogd web server

docs/draft/howto/catalog-queries-graphql-endpoint.md

@@ -0,0 +1,200 @@
+# Catalog queries using GraphQL
+
+!!! warning "Alpha Feature"
+    The GraphQL endpoint is an **alpha feature** controlled by the `GraphQLCatalogQueries` feature gate.
+    The API and behavior may change in future releases.
+
+After you [add a catalog of extensions](../../tutorials/add-catalog.md) to your cluster, you can query the catalog using GraphQL for flexible, structured queries with precise field selection.
+
+## Prerequisites
+
+* You have added a ClusterCatalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster.
+* The `GraphQLCatalogQueries` feature gate is enabled in catalogd.
+
+!!! note
+    By default, Catalogd is installed with TLS enabled for the catalog webserver.
+    The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag.
+
+You also need to port forward the catalog server service:
+
+``` terminal
+kubectl -n olmv1-system port-forward svc/catalogd-service 8443:443
+```
+
+## GraphQL Endpoint
+
+The GraphQL endpoint is available at:
+
+```
+https://localhost:8443/catalogs/<catalog-name>/api/v1/graphql
+```
+
+All queries must be sent as **HTTP POST** requests with a JSON body containing a `query` field.
+
+## Understanding GraphQL Field Names
+
+**IMPORTANT**: GraphQL field names are automatically generated from catalog schema names.
+
+### Naming Convention
+
+Schema names are converted to GraphQL field names using this process:
+
+1. Remove dots and special characters: `olm.bundle` → `olmbundle`
+2. Convert to lowercase: `OLM.Bundle` → `olmbundle`  
+3. Append 's' for pluralization: `olmbundle` → `olmbundles`
+
+**Examples:**
+
+| Schema Name | GraphQL Field Name |
+|-------------|-------------------|
+| `olm.bundle` | `olmbundles` |
+| `olm.package` | `olmpackages` |
+| `olm.channel` | `olmchannels` |
+| `helm.chart` | `helmcharts` |
+
+### Discovering Available Fields
+
+To find the exact field names available for your catalog, use GraphQL introspection:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ __schema { queryType { fields { name description } } } }"
+  }' | jq
+```
+
+This returns all available query fields for the catalog, including the automatically generated schema-based fields.
+
+!!! warning "Pluralization Limitations"
+    The current implementation appends 's' to schema names for pluralization. This may not produce grammatically correct English plurals in all cases (e.g., `index` → `indexs` instead of `indices`). When creating custom schemas, use singular nouns that pluralize well with a simple 's' suffix.
+
+## Basic Queries
+
+### Catalog Summary
+
+Get an overview of schemas and object counts in the catalog:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ summary { totalSchemas schemas { name totalObjects totalFields } } }"
+  }' | jq
+```
+
+### Query Bundles
+
+List bundles with specific fields:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 5, offset: 0) { name package image } }"
+  }' | jq
+```
+
+### Query Packages
+
+List packages with metadata:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmpackages(limit: 10) { name description defaultChannel } }"
+  }' | jq
+```
+
+### Query Channels
+
+List channels:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmchannels { name package entries } }"
+  }' | jq
+```
+
+## Advanced Queries
+
+### Pagination
+
+All schema-based queries support pagination via `limit` and `offset` arguments:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 10, offset: 20) { name } }"
+  }' | jq
+```
+
+### Nested Field Selection
+
+Select only the fields you need, including nested objects:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmpackages { name icon { mediatype base64data } } }"
+  }' | jq
+```
+
+### Complex Bundle Properties
+
+Query bundle properties (which use union types for variable structures):
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 5) { name properties { type value } } }"
+  }' | jq
+```
+
+## Comparing GraphQL vs Metas Endpoint
+
+| Feature | GraphQL (`/api/v1/graphql`) | Metas (`/api/v1/metas`) |
+|---------|---------------------------|------------------------|
+| Field selection | Precise - request only needed fields | All fields always returned |
+| Query complexity | Rich queries with nested objects | Simple parameter-based filtering |
+| Response size | Minimal - only requested data | Full objects always returned |
+| Schema discovery | Introspection built-in | External documentation needed |
+| Pagination | Built-in `limit` and `offset` | Manual implementation required |
+| HTTP Method | POST only | GET supported |
+| Feature status | Alpha (feature gate required) | Stable |
+
+**When to use GraphQL:**
+- You need specific fields from large objects
+- You want to query related data in a single request
+- You need structured, typed responses
+- You're building a UI or client that benefits from precise data fetching
+
+**When to use Metas endpoint:**
+- You need simple, stable API
+- You're doing basic filtering by schema/package/name
+- You want to use GET requests for caching
+- You need guaranteed API stability
+
+## Limitations
+
+1. **Pluralization**: Schema names are pluralized by appending 's', which may not be grammatically correct for all words
+2. **Schema naming**: Full schema names (including namespace/prefix) are preserved in field names (`olm.bundle` → `olmbundles`, not `bundles`)
+3. **POST only**: GraphQL endpoint only accepts POST requests, unlike the metas endpoint which supports GET
+4. **Alpha stability**: API may change in future releases while in alpha
+
+## Enabling the GraphQL Feature
+
+The GraphQL endpoint is controlled by the `GraphQLCatalogQueries` feature gate. To enable it:
+
+``` yaml
+args:
+  - --feature-gates=GraphQLCatalogQueries=true
+```
+
+See [enable webhook support](enable-webhook-support.md) for more details on configuring feature gates.

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/google/go-containerregistry v0.21.4
 	github.com/google/renameio/v2 v2.0.2
 	github.com/gorilla/handlers v1.5.2
+	github.com/graphql-go/graphql v0.8.1
 	github.com/klauspost/compress v1.18.5
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.1
@@ -144,7 +145,6 @@ require (
 	github.com/gorilla/mux v1.8.1 // indirect
 	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
 	github.com/gosuri/uitable v0.0.4 // indirect
-	github.com/graphql-go/graphql v0.8.1 // indirect
 	github.com/gregjones/httpcache v0.0.0-20190611155906-901d90724c79 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.7 // indirect
 	github.com/h2non/filetype v1.1.3 // indirect

helm/experimental.yaml

@@ -23,5 +23,6 @@ options:
     features:
       enabled:
         - APIV1MetasHandler
+        - GraphQLCatalogQueries
 # This can be one of: standard or experimental
   featureSet: experimental

internal/catalogd/features/features.go

@@ -9,13 +9,13 @@ import (
 )
 
 const (
-	APIV1MetasHandler = featuregate.Feature("APIV1MetasHandler")
+	APIV1MetasHandler     = featuregate.Feature("APIV1MetasHandler")
 	GraphQLCatalogQueries = featuregate.Feature("GraphQLCatalogQueries")
 )
 
 var catalogdFeatureGates = map[featuregate.Feature]featuregate.FeatureSpec{
-	APIV1MetasHandler: {Default: false, PreRelease: featuregate.Alpha},
-	GraphQLCatalogQueries: {Default: false, PreRelease: featuregate.Alpha},
+	APIV1MetasHandler:     {Default: false, PreRelease: featuregate.Alpha, LockToDefault: false},
+	GraphQLCatalogQueries: {Default: false, PreRelease: featuregate.Alpha, LockToDefault: false},
 }
 
 var CatalogdFeatureGate featuregate.MutableFeatureGate = featuregate.NewFeatureGate()

internal/catalogd/graphql/README.md

@@ -2,6 +2,8 @@
 
 This package provides dynamic GraphQL schema generation for operator catalog data, integrated into the catalogd storage server.
 
+⚠️ **Alpha Feature**: This is an experimental feature controlled by the `GraphQLCatalogQueries` feature gate. See user documentation at `docs/draft/howto/catalog-queries-graphql-endpoint.md`.
+
 ## Usage
 
 The GraphQL endpoint is now available as part of the catalogd storage server at:
@@ -43,7 +45,7 @@ curl -X POST http://localhost:8080/my-catalog/api/v1/graphql \
 #### Get bundles with pagination:
 ```graphql
 {
-  bundles(limit: 5, offset: 0) {
+  olmbundles(limit: 5, offset: 0) {
     name
     package
     version
@@ -54,17 +56,28 @@ curl -X POST http://localhost:8080/my-catalog/api/v1/graphql \
 #### Get packages:
 ```graphql
 {
-  packages(limit: 10) {
+  olmpackages(limit: 10) {
     name
     description
   }
 }
 ```
 
+#### Get channels:
+```graphql
+{
+  olmchannels(limit: 10) {
+    name
+    package
+    entries
+  }
+}
+```
+
 #### Get bundle properties (union types):
 ```graphql
 {
-  bundles(limit: 5) {
+  olmbundles(limit: 5) {
     name
     properties {
       type
@@ -92,15 +105,58 @@ curl -X POST http://localhost:8080/my-catalog/api/v1/graphql \
 
 ## Integration
 
-The GraphQL functionality is integrated into the `LocalDirV1` storage handler in `internal/catalogd/storage/localdir.go`:
+The GraphQL functionality is integrated across multiple packages:
 
-- `handleV1GraphQL()`: Handles POST requests to the GraphQL endpoint
-- `createCatalogFS()`: Creates filesystem interface for catalog data
-- `buildCatalogGraphQLSchema()`: Builds dynamic GraphQL schema for specific catalogs
+- `internal/catalogd/server/handlers.go`: `CatalogHandlers.handleV1GraphQL()` handles POST requests to the GraphQL endpoint
+- `internal/catalogd/storage/localdir.go`: `LocalDirV1.GetCatalogFS()` creates filesystem interface for catalog data
+- `internal/catalogd/service/graphql_service.go`: `GraphQLService.GetSchema()` and `buildSchemaFromFS()` build dynamic GraphQL schemas for specific catalogs
 
 ## Technical Details
 
 - Uses `declcfg.WalkMetasFS` to discover schema structure
 - Generates GraphQL object types dynamically from discovered fields
 - Creates union types for bundle properties with variable structures
-- Supports all standard GraphQL features including introspection 
+- Supports all standard GraphQL features including introspection
+
+## Field Naming Conventions
+
+### Schema to GraphQL Field Name Mapping
+
+**IMPORTANT**: GraphQL field names are automatically generated from schema names using the following convention:
+
+1. **Remove dots and special characters** - `olm.bundle` becomes `olmbundle`
+2. **Convert to lowercase** - `OLM.Bundle` becomes `olmbundle`
+3. **Append 's' for pluralization** - `olmbundle` becomes `olmbundles`
+
+**Examples:**
+- `olm.bundle` → `olmbundles`
+- `olm.package` → `olmpackages`
+- `olm.channel` → `olmchannels`
+- `helm.chart` → `helmcharts`
+- `custom.operator` → `customoperators`
+
+### Limitations and Considerations
+
+⚠️ **Pluralization Limitations**: The current implementation blindly appends 's' to create plural field names. This approach has known limitations:
+
+1. **English grammar rules not applied**: Words ending in 's', 'x', 'z', 'ch', 'sh' should use 'es', but currently just get 's' appended
+2. **Irregular plurals not supported**: Schema names like `person`, `child`, `index` will become `persons`, `childs`, `indexs` instead of proper English plurals
+3. **Non-English schema names**: Schemas using non-English words will not follow appropriate pluralization rules for their language
+4. **Already-plural names**: If a schema name is already plural, it will still get 's' appended
+
+**Recommendations for schema naming:**
+- Use schema names that work well with simple 's' pluralization (e.g., `bundle`, `package`, `chart`)
+- Avoid schema names that are already plural or have irregular plural forms
+- Document the expected GraphQL field names in your catalog documentation
+- Use GraphQL introspection to discover actual field names: `{ __schema { queryType { fields { name } } } }`
+
+### Field Name Sanitization
+
+All field names within objects are sanitized to be valid GraphQL identifiers:
+
+- Special characters (dots, hyphens, etc.) are replaced with underscores
+- CamelCase conversion: `package-name` → `packageName`, `default_channel` → `defaultChannel`
+- Names starting with numbers get `field_` prefix: `123invalid` → `field_123invalid`
+- Empty or invalid names default to `value`
+
+See `remapFieldName()` function for complete logic.