go: document embedding and publish duckdb-server-go module releases

[derekperkins]

Summary

Document the supported embedding workflow and establish a repeatable release path for the nested duckdb-server-go module after its public packages are stable.

The repository currently documents go install -tags=duckdb_arrow ...@latest, but the newest matching module tag is packages/server/duckdb-server-go/v0.21.1. There are multiple later Go-server changes on main, including the authorization hardening in #1106 and #1117-#1121. External consumers need a tag that actually contains the reusable packages and current security behavior.

Documentation

Add concise examples for:

• importing and constructing pkg/query;
• serving pkg/server with a caller-owned http.Server;
• wrapping the handler with normal authentication/observability middleware;
• installing the optional command authorizer and schema-header example;
• configuring the reusable extension initializer; and
• deterministic shutdown and resource ownership.

Also document:

• the required duckdb_arrow build tag;
• the minimum supported Go version;
• concurrency and cache semantics that callers may rely on;
• which errors are safe to classify with errors.Is;
• the difference between the reusable libraries and the module-root example binary;
• that the example server and its policies are candidate implementations, not a Mosaic protocol/security standard; and
• the limits of SQL authorization: it is not process, filesystem, network, extension, catalog, or credential isolation.

Keep flag parsing, localhost TLS discovery, process logging, and listen/shutdown policy in the example binary unless there is a separate reason to make them reusable. Publishing the packages should not freeze every behavior currently in main.go.

Release path

• Define how and when tags matching the nested module path are cut: packages/server/duckdb-server-go/vX.Y.Z.
• Prefer an automated or documented release check that refuses to tag until the Go tests/lint pass and the tag points at the intended commit.
• Decide and state the compatibility policy while the module is pre-v1. Accidental exports from the mechanical move are not automatically stable APIs.
• Verify both library consumption and binary installation through the public Go proxy/module tooling.

Acceptance criteria

• A checked-in external-package example imports only the supported pkg/query, pkg/server, and extension APIs.
• CI or a temporary-module test runs that example with duckdb_arrow, outside the package-under-test namespace.
• README import/install commands use an available module version and explain when @latest is appropriate.
• A new correctly named nested-module tag is published only after go: publish query and server packages under pkg #1123, go: minimize and harden the public pkg/query API #1124, go: extract reusable DuckDB extension initialization #1125, go: add pluggable per-command authorization to pkg/server #1126, and go: reimplement schema-match headers as an authorizer #1127 are complete.
• go list -m github.com/uwdata/mosaic/packages/server/duckdb-server-go@latest resolves to that tag.
• go install -tags=duckdb_arrow github.com/uwdata/mosaic/packages/server/duckdb-server-go@latest builds the example binary.
• A fresh external module can go get the tagged version and compile the documented embedding example.
• Release notes call out the new public packages and the current fail-closed authorization limitations.

Sequencing

This is the final integration/publication issue. Documentation can be drafted alongside implementation, but the compatibility statement and module tag follow the public API, extension, generic authorization, and schema-adapter work.