docs: service catalog — guides, ADR-028, migration, resolvers + regenerated API reference#46
Merged
Merged
Conversation
Document the service-catalog feature (ctx.call / ctx.stream, defineService, catalogs, remote resolvers): - guide/service-communication/service-catalog.md — defineService, catalog + codegen, ctx.call / ctx.stream, the signal/deadline/header cascade, enabledServices, server.client, and the split error model. - guide/service-communication/resolvers.md — RemoteResolver contract (synchronous, lazy, no startup I/O) + built-in single/map/dns/per-service-env resolvers, endpoint hints, mock testing. - migration/service-catalog.md — ServiceRoute → defineService and server.client fallback → remoteResolver, before/after + checklist. - contributing/adr/028-service-catalog.md — the architectural decisions. - Sidebar + ADR index updated. `vitepress build` passes (no dead links). Every signature was verified against the @connectum/core / @connectum/testing / @connectum/protoc-gen-catalog source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Regenerate the TypeDoc API reference from @connectum/core (and testing) on the service-catalog feature branch: adds defineService / defineLazyService, defineCatalog / mergeCatalogs, the Context (ctx.call / ctx.stream) + stream handle types, RemoteResolver + built-in resolvers, CatalogConfigError, defaultPropagateHeaders, and the @connectum/testing mock helpers. Removes the deleted ServiceRoute type. `vitepress build` passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…inks
Update pre-existing guides that still described the removed API or linked to
deleted examples:
- ServiceRoute `(router) => void` registration → `defineService` (packages/core,
guide/production/architecture, index hero, quickstart, service-communication/
patterns).
- `server.client(Desc, { fallback })` → configure `createServer({ remoteResolver })`;
not-local + no resolver throws CatalogConfigError (not ConnectError/Unimplemented
at construction); resolver null → ConnectError(Unavailable).
- production guides (docker / kubernetes / service-mesh / envoy-gateway) pointed
at the deleted examples/production-ready/ — repoint to examples/car-sharing/
(k8s / istio / Dockerfile); drop dead envoy-gateway links (Istio embeds Envoy).
- cli-commands: examples/basic-service/* → examples/getting-started/*.
`vitepress build` passes (no dead internal links).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Regenerate the TypeDoc API reference from connectum feature/service-catalog so it reflects the final shipped surface: the `ServiceOptions` type and the `defineService(descriptor, handlers, options?)` third argument, `Context.call` / `Context.stream`, the resolver helpers, and the catalog primitives. Clean regeneration (removed stale pages for renamed/removed symbols). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A scoped audit of the service-catalog docs against the final connectum source surfaced several contract mismatches and navigation bugs: - server.client(): a resolver returning null fails at client construction (the resolver runs inside server.client(), before any RPC), not "at call time" — corrected in in-process-transport and packages/core. - ADR-028 described a validateAtStartup resolver-probe option that does not exist; startup validation is a shape check only (enabledServices ⊆ catalog). - packages/core CreateServerOptions table was missing the five catalog fields (catalog, enabledServices, remoteResolver, outgoingInterceptors, propagateHeaders) and the Exports Summary omitted the catalog exports. - service-catalog guide: ctx.stream takes only a method key; CallOptions go to the returned factory, not to ctx.stream itself. - migration guide: restore the per-service options example now that defineService accepts a third ServiceOptions argument. - cli-commands: drop the coordination-root gen-api-docs.sh reference and the example pending removal; fix two dead /guide/typescript anchors to their dedicated subpages (also in packages/core and quickstart). vitepress build passes (no dead internal links). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ures The two packages new in 1.0.0 had no guide/package page (only auto-generated API reference). Add dedicated pages (modeled on the existing package pages) and sidebar entries. vitepress build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Regenerated the TypeDoc API reference (pnpm docs:api) against connectum main at 1.0.0 (post-#137). Reflects the final 1.0.0 surface — including the service-catalog exports, the EffectiveTransport/TransportValidationMode value exports, and the testing/test-fixtures split. vitepress build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the auto-generated en/api/ directory to the structure tree and relabel en/packages/ as per-package guides (the API reference lives in en/api/). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
What
Documentation for the service catalog feature: declarative cross-service
calls (
defineService,ctx.call/ctx.stream,remoteResolver, the catalogprimitives,
enabledServices,propagateHeaders).service-communication/service-catalog,service-communication/resolvers.migration/service-catalog—ServiceRoute→defineService,server.client({ fallback })→remoteResolver, and per-service options.packages/core.en/api/**) against the final framework surface — includesServiceOptions, thedefineService(descriptor, handlers, options?)third argument,Context.call/Context.stream, the resolver helpers, and the catalog primitives.Quality
A scoped audit of these docs against the framework source fixed several contract
mismatches before publishing:
server.client()error timing: anull-returning resolver fails at client construction (the resolver runs insideserver.client()), not at call time.validateAtStartupresolver-probe option that does not exist — startup validation is a shape check only (enabledServices ⊆ catalog).CreateServerOptionsreference table was missing the five catalog fields; the Exports Summary omitted the catalog exports.ctx.streamtakes only a method key —CallOptionsgo to the returned factory.defineServiceaccepts a thirdServiceOptionsargument./guide/typescriptanchors (now point at the dedicated subpages).vitepress buildpasses with no dead internal links.Coordination notes (for the reviewer/merger)
car-sharingando11y-corootexamples) resolve only once the corresponding examples branch is pushed and merged to itsmain. They are external links and do not affect the docs build.