Content API requests were all accepted via POST (as detailed in the
GraphQL spec) and not amenable to caching.
Now, requests are also accepted via GET (as optionally allowed for query
requests only), and cached.
Also sent the request method to Logflare so we can track the ratio of
GET/POST requests.
* refactor: reading markdown docs files
Refactor how Markdown docs files are read:
- Reuses the same logic across search index generation & page generation
- Improves the indexed content for search:
- Stops removing MDX components, which often contain useful
information like Admonitions
- Denormalizes Partials and CodeSamples for more complete content
This is a prerequisite step for implementing the "Copy docs as Markdown"
functionality.
Only touches regular guides for now, not federated ones.
* fix: tailwind build error (#37728)
We changed to default to ESM imports a while ago, which means local
builds are now breaking because the Tailwind uses a require. Changed to
CJS for Tailwind config file. (I have no idea how this has been working
on Vercel all this time.)
* style: prettier
Implement hybrid search for the /docs/api/graphql searchDocs endpoint. Prepend a more descriptive title and introduction to database advisor docs so they rank more highly when directly searched for.
Add the ability to look up error code explanation in API Gateway logs.
Also a bunch of GraphQL-related utilities and generated types for
calling the Content API.
* docs: add cursor rule for embedding generation process
Add documentation for cursor IDE about how docs embeddings are generated,
including the workflow for creating and uploading semantic search content.
* feat: improve API reference metadata upload with descriptive content
- Add preembeddings script to run codegen before embedding generation
- Enhance OpenApiReferenceSource to generate more descriptive content including
parameters, responses, path information, and better structured documentation
* feat: add Management API references to searchDocs GraphQL query
- Add ManagementApiReference GraphQL type and model for API endpoint search results
- Integrate Management API references into global search results
- Update test snapshots and add comprehensive test coverage for Management API search
* style: format
Sentry errors captured on routes run on Edge are not getting properly
sent. This is apparently a known issue where Vercel closes the process
before Sentry can flush, so the exceptions need to be manually flushed:
https://github.com/getsentry/sentry-javascript/issues/9626
- Add support for filtering errors by specific error codes
- Implement `errors` query that accepts array of error code IDs
- Add tests for error code filtering functionality
- Update GraphQL schema with new error filtering capabilities
* feat(graphql): add paginated errors collection query
- Add new GraphQL query field 'errors' with cursor-based pagination
- Add UUID id column to content.error table for cursor pagination
- Implement error collection resolver with forward/backward pagination
- Add comprehensive test suite for pagination functionality
- Update database types and schema to support new error collection
- Add utility functions for handling collection queries and errors
- Add seed data for testing pagination scenarios
This change allows clients to efficiently paginate through error codes using cursor-based pagination, supporting both forward and backward traversal. The implementation follows the Relay connection specification and includes proper error handling and type safety.
* docs(graphql): add comprehensive GraphQL architecture documentation
Add detailed documentation for the docs GraphQL endpoint architecture, including:
- Modular query pattern and folder structure
- Step-by-step guide for creating new top-level queries
- Best practices for error handling, field optimization, and testing
- Code examples for schemas, models, resolvers, and tests
* feat(graphql): add service filtering to errors collection query
Enable filtering error codes by Supabase service in the GraphQL errors collection:
- Add optional service argument to errors query resolver
- Update error model to support service-based filtering in database queries
- Maintain pagination compatibility with service filtering
- Add comprehensive tests for service filtering with and without pagination
* feat(graphql): add service filtering and fix cursor encoding for errors collection
- Add service parameter to errors GraphQL query for filtering by Supabase service
- Implement base64 encoding/decoding for pagination cursors in error resolver
- Fix test cursor encoding to match resolver implementation
- Update GraphQL schema snapshot to reflect new service filter field
* docs(graphql): fix codegen instruction
* feat(content api): add error endpoint
Add an endpoint to return the details of a Supabase error, given the
error code and service.
Schema additions:
```graphql
type RootQueryType {
"...previous root queries"
"""Get the details of an error code returned from a Supabase service"""
error(code: String!, service: Service!): Error
}
"""An error returned by a Supabase service"""
type Error {
"""
The unique code identifying the error. The code is stable, and can be used for string matching during error handling.
"""
code: String!
"""The Supabase service that returns this error."""
service: Service!
"""The HTTP status code returned with this error."""
httpStatusCode: Int
"""
A human-readable message describing the error. The message is not stable, and should not be used for string matching during error handling. Use the code instead.
"""
message: String
}
enum Service {
AUTH
REALTIME
STORAGE
}
```
* test(content api): add tests for top-level query `error`
Alter the docs test script so it spins up Supabase locally. Will allow
for end-to-end tests against the local DB.
Also small alteration to one of the test files to silence an annoying
(but intended) error.
* feat(content api): add client library api reference search results
Allow searchDocs results to also return function references from the
client library APIs
* fix(content api): refine language enum handling
Add a top-level field to search docs globally. Right now this only
returns Markdown guides (not references, GitHub discussions, or partner
pages.
The full GraphQL schema at this point:
```
schema {
query: RootQueryType
}
type RootQueryType {
"""Get the GraphQL schema for this endpoint"""
schema: String!
"""Search the Supabase docs for content matching a query string"""
searchDocs(query: String!, limit: Int): SearchResultCollection
}
"""A collection of search results containing content from Supabase docs"""
type SearchResultCollection {
"""A list of edges containing nodes in this collection"""
edges: [SearchResultEdge!]!
"""The nodes in this collection, directly accessible"""
nodes: [SearchResult!]!
"""The total count of items available in this collection"""
totalCount: Int!
}
"""An edge in a collection of SearchResults"""
type SearchResultEdge {
"""The SearchResult at the end of the edge"""
node: SearchResult!
}
"""Document that matches a search query"""
interface SearchResult {
"""The title of the matching result"""
title: String
"""The URL of the matching result"""
href: String
"""The full content of the matching result"""
content: String
}
```
Towards DOCS-214
* feat (content api): add top-level schema query
Adds a top-level schema query that returns the stringified GraphQL
schema for this endpoint. Useful for LLMs to access the stringified
schema for prompting and tool calls.
Query shape:
```
query Search {
schema
}
```
Query response:
```
{
"data": {
"schema": "schema {\n query: RootQueryType\n}\n\ntype RootQueryType
{\n \"\"\"Get the GraphQL schema for this endpoint\"\"\"\n schema:
String\n}"
}
}
```
Towards DOCS-214
* test (content api): add schema snapshot
Add schema snapshot test to prevent unintentional changes to public API
for this endpoint
* fixup! feat (content api): add top-level schema query
* fix (content api): local dev introspection
The validation rules that are used for security in production are
preventing GraphiQL from introspecting the schema in dev. Since this DX
feature is incredibly useful, I'm turning off the complexity and depth
validations for dev GraphiQL only. Local curls, etc., will still have
production-standard validation so it can be tested locally.
GraphQL errors were occasionally returned as normal HTTP status code
errors, switched to using only GraphQL-spec compliant errors for the
/docs/api/graphql endpoint.
Continue building out the docs/api/graphql endpoint by adding more
validation:
-A query depth limiter
- A query complexity limiter
Also added dummy (empty) root resolver and schema, plus a dev-only
GraphiQL page for better DX.
Endpoint should still return a 404 for now as there is no resolver.
The first PR in a series to build out the Content API. Adds a dummy
GraphQL route with some tests: for now all this does is validate the
request body and return a 404.
Charis