docs: document the gRPC-Web interface (GA in 1.39) - #491
Merged
Conversation
Weaviate serves gRPC-web under the /v1/grpc-web/ path prefix on the existing REST port, so browsers can reach the gRPC API without a second listener. Enabled by default; toggled at runtime with grpc_web_enabled. No client library speaks gRPC-web yet, so this states that the interface exists without implying a supported client path or a runnable example. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
In Weaviate Cloud the gRPC-web interface is reached through the REST Endpoint URL rather than the gRPC Endpoint URL, because it is served on the REST port. Added to the existing "REST Endpoint vs gRPC Endpoint" admonition on the connect page, which already owns this distinction. The default cluster settings page was considered and rejected: it is a table of setting defaults with no endpoint content. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
grpc_web_enabled has no environment variable. Core only ever seeds it with a default DynamicValue and has no os.LookupEnv branch, unlike DEBUG_ENDPOINTS_ENABLED, so it can be set only as a runtime override. - Add the override to the General table with the environment variable column marked "not applicable" rather than left blank or invented. - Soften the page's blanket claim that every runtime configuration corresponds to an existing environment variable. - State on the gRPC API page that there is no environment variable equivalent, so readers who know the convention stop looking. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
- Use the protocol's own capitalisation, gRPC-Web, in prose. Code-font /v1/grpc-web/, grpc_web_enabled and the #grpc-web anchor are unchanged, so cross-links still resolve. - Say to set the override to false rather than leaving the value implied. - Promote the section to a "## gRPC-Web" sibling so the matched Server-side / Client-side pair is no longer split. - Give the no-environment-variable sentence a subject and attach it to the enablement idea. - Drop the rest/REST collision and the vague antecedent. - Tie the client-library guard to the browser framing so it cannot be misread as contradicting client gRPC support. - Make the cloud sentence second person, matching its admonition. - Avoid a third term for the same concept on the runtime-config page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
The interface can be turned off in two places, and core spells the key differently in each: grpc.grpcWebEnabled in the static configuration file, grpc_web_enabled as a runtime override. Present them as a short list so the camelCase/snake_case split cannot be skimmed past. Also correct the runtime-config note, which claimed the setting could only be set as a runtime override. That is now false. The separate "no environment variable equivalent" statement stands: a configuration file field is not an environment variable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Secrets |  0  0  0  0 |
View in Orca |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
gRPC-Web had no coverage anywhere in the docs. It is being declared GA with 1.39, though the endpoint itself shipped in v1.38.3, so the version marker cites v1.38.3 and the GA declaration rides the release.
Scope is deliberately small: two mentions plus one factual correction. No new page.
Changes
weaviate/api/grpc.md— new## gRPC-Websection covering: served on the REST port under/v1/grpc-web/rather than a dedicated listener, so there is no second port to expose; enabled by default; both ways to turn it off; and that no client library uses it yet.cloud/manage-clusters/connect.mdx— one line in the existing "REST Endpoint vs gRPC Endpoint" admonition, noting gRPC-Web is reached through the REST endpoint URL.deploy/configuration/env-vars/runtime-config.md— adds thegrpc_web_enabledrow, and corrects a claim that is now false. The page stated "Each runtime configuration corresponds to an existing environment variable"; gRPC-Web has no environment variable, so that is softened to "Most" with a note that some overrides have no env-var equivalent. The row's env-var column reads_(not applicable)_, matching the table's existing italic-parenthetical idiom.The casing split is deliberate
The off-switch is spelled differently in each place, which is the kind of thing an operator loses time to, so it is presented as a two-item list rather than buried in a sentence:
grpc.grpcWebEnabled(camelCase)grpc_web_enabled(snake_case)Verification
Facts checked against core at
v1.38.3,v1.38.8andv1.39.0-rc.1:Mount("/v1/grpc-web", ...)inadapters/handlers/rest/configure_api.goGrpcWebEnabledOrDefault()returns true when unset, so enabled by defaultGrpcWebEnabledtaggedgrpcWebEnabledinconfig_handler.go;grpc_web_enabledinruntimeconfig.go; registered by pointer, so overrides apply without a restartGRPC_WEB*token anywhere inusecases/configat any of the three tags, so there genuinely is no environment variablev1.38.2contains no gRPC-Web at all, soAdded in v1.38.3is exactSite builds; warning set is byte-identical to base. The new
#grpc-webanchor was confirmed in rendered HTML (it slugifies to lowercase despite the capital W), and both inbound links resolve. No code snippets added.Known gaps, not addressed here
weaviate/typescript-client#307is still open. The text says so plainly rather than implying a usage path, and that sentence will need removing when a client ships.CORS_ALLOW_ORIGINdefaults to the console origin, which may block browser apps served from elsewhere. Nothing here claims otherwise, but it is the obvious next question.