Files
e8b9dbff2f fix: fill collection_name and keep request id in DescribeCollection queried by id (#51313)
issue: #51253

> Rebased on master after #51254 merged. The `db_name`/`db_id` part of
the original PR is now covered by #51254; this PR is reduced to the two
remaining gaps on the same query-by-id path.

## Problem

When `DescribeCollection` is called with **only a `collectionID`** — no
collection name, no db name (e.g. the HTTP management API on `:9091`) —
two gaps remain after #51254:

1. **Top-level `collection_name` is empty** on both the cached provider
path and the `describeCollectionTask` path. The response is initialized
from the (empty) `request.CollectionName` before the name is resolved,
and never backfilled.
2. **The cached provider discards the caller-provided collection id.**
After deriving the name from the id, it re-resolves the id from that
name via `GetCollectionID(db, name)`. Id-only lookups are cached under
the request db name — empty here — so with same-name collections in
different databases, a concurrent cache refresh can rebind the entry
under the `""` key and the request would silently describe the wrong
collection (the derived name matches, the id does not).

## Fix

- `service_provider.go`:
- Backfill `resp.CollectionName` from the resolved cached schema when
the request carried no name. Requests that pass a name (including
aliases) still echo it unchanged.
- Skip the name→id re-resolution when the caller already supplied the
id. `GetCollectionInfo` already validates the cache entry against the id
(`collInfo.collID != collectionID` → refresh by id), so the
caller-provided id is authoritative end to end. Name+id requests keep
the existing name-precedence behavior.
- Resolve identifiers on local copies instead of rewriting
`request.CollectionName`/`CollectionID` in place — the access log
interceptor and the success metric labels serialize the request after
the handler returns, and previously recorded the resolved values instead
of what the client sent.
- `task.go`: backfill `t.result.CollectionName` from the coordinator
result on the non-cached path.
- `meta_cache.go`: fix a stale comment on `ResolveCollectionAlias` —
`update()` now always keys `collInfo` by the real collection name
(aliases live in the separate alias map), the old comment described
pre-refactor behavior.
- Tests:
-
`TestCachedProxyServiceProvider_DescribeCollection_ByIDFillsNameAndUsesRequestID`:
drives the id-only path; `GetCollectionID` is deliberately not mocked,
so any regression back to re-resolving the id panics the test.
- `TestDescribeCollectionTask_FillsNameFromResultWhenQueriedByID`: same
assertion for the non-cached path.
- Removed the now-unused `GetCollectionID` expectation from the test
added in #51254 (that call no longer happens on the id-only path).

## Follow-up commit: entity-keyed meta cache with a cluster-wide id
index

Reviewing this path surfaced a deeper issue in the proxy meta cache,
fixed in the second commit:

- By-id lookups (`GetCollectionName`, `GetCollectionInfo` with an empty
name) linearly scanned a whole db bucket under the read lock, on every
request even on cache hits.
- The bucket scanned/filled was keyed by the *request* db name — empty
for id-only calls — so entries landed in a bogus `""` bucket: a
collection also cached under its real db was duplicated, and same-name
collections of different databases evicted each other from the single
`""`-keyed slot.

The cache is now entity-keyed instead of request-keyed:

- Fills land under the collection's **actual database** (carried in the
describe response); the `""` bucket no longer exists.
- A cluster-wide `collectionID → entry` index serves by-id lookups in
**O(1)** regardless of the request db — matching rootcoord, which
resolves by-id describes straight from `collID2Meta` without consulting
the db name.
- Name lookups normalize an empty db name to `default`, mirroring
rootcoord's backward-compat normalization
(`meta_table.getCollectionByNameInternal`). This also closes a latent
cross-database mis-hit: a name lookup with an empty db could previously
return whichever same-name collection was last id-cached under the `""`
bucket.
- All removal paths maintain the index (pointer-identity-guarded
unindexing); invalidation sweeps stay exhaustive.

## Verification

- Ran locally against a current master core build: the full
`TestMetaCache*`, `TestCachedProxyServiceProvider*`,
`TestDescribeCollectionTask*`, alias and partition test sets all pass,
plus the **full `internal/proxy` suite** (only the pre-existing
etcd-dependent `TestProxyRpcLimit` fails locally — it needs a live etcd,
unrelated to this change).
- New tests:
`TestCachedProxyServiceProvider_DescribeCollection_ByIDFillsNameAndUsesRequestID`
(id-only path; also asserts the request is not rewritten),
`TestDescribeCollectionTask_FillsNameFromResultWhenQueriedByID`,
`TestMetaCache_ByIDIndexRealDBBucket` (same-name collections in two
databases filled by id: no eviction, entries under real dbs, by-name
reuses by-id fill, every removal path cleans the index),
`TestMetaCache_EmptyDBNameSharesDefaultEntry`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


---

## Update: proxy meta cache rebuilt around an id-primary store (2 new
commits)

Following review discussions on invalidation cost and the alias-DDL
races, this PR now also rebuilds the cache (issue: #51533, design doc:
`docs/design-docs/design_docs/20260716-proxy-metacache-id-inverted-index.md`
in this PR):

1. **`fix: forward the pre-alter alias target id in the AlterAlias
expiration`** — rootcoord resolves the pre-alter target under its
database lock and carries it in the new additive
`AlterAliasMessageHeader.old_collection_id`; the ack callback emits a
second expiration entry so proxies evict BOTH AlterAlias targets by id.
Closes the race where a concurrent Describe re-points the proxy's alias
resolution before the expiration arrives, leaving the old target
permanently stale. Older rootcoords (field 0) fall back to the proxy's
hint resolution.
2. **`enhance: rebuild the proxy meta cache around an id-primary
store`** — the primary store is keyed by the cluster-unique collection
id (single source of truth, with a per-database generation); name/alias
resolution become hints validated against the primary on read; partition
caches are keyed by id; fills are ordered against invalidations by a
fill RWMutex (drain in-flight describes before evicting), replacing the
per-collection timestamp floor. Every invalidation becomes O(1) — no
more full-cache scans under the write lock on
Load/Release/Drop/Rename/Alter broadcasts, and
DropDatabase/AlterDatabase becomes a generation bump. Also removes a
latent stale read (alias-keyed partition entries surviving
DropCollection).

Verification: targeted cache suites green (rename, alias re-point under
concurrent describe, drop+recreate with a reused name, db-generation
invalidation, cross-db isolation, gated-mock fill/invalidation
ordering); three negative controls (hint validation / dbGen check / fill
drain disabled) each fail exactly the test guarding them; full-package
`-race` delegated to CI.


---

## Update: simplification series (final form)

Following design review, the cache was iteratively simplified to an
**id-primary store with declared hints** — every mechanism that could be
replaced by an invariant was deleted (net-negative diffs throughout):

- Primary store keyed by the cluster-unique collection id; liveness IS
presence. Name/alias resolution are hints written ONLY together with
their entry (declared aliases) and validated against the primary on
every read — a stale hint can only cost one extra describe, never a
stale read.
- Fill/invalidation ordering via a fill RWMutex (drain in-flight
describes before evicting); the per-collection timestamp floor, database
generations, background GC, alias negative cache, per-partition cache,
and the resolve-and-forget DescribeAlias path are all **deleted**.
Evictions clean everything the entry owns synchronously; **no
invalidation path performs any RPC**.
- Old-rootcoord fallbacks: id-describes without DbName are served
uncached; alias-DDL broadcasts without ids trigger hint resolution plus
a holder scan **gated on that exact fingerprint** (dead code once
rootcoords are upgraded), closing the ghost-alias case with no healing
event.
- **Accepted gaps (WONT-FIX)** are recorded in the design doc §6 —
notably the upgrade-window new-target `Aliases` display lag (the
association exists only at rootcoord; self-heals on first use;
display-only).

See
`docs/design-docs/design_docs/20260716-proxy-metacache-id-inverted-index.md`
for the full design, invariants and trade-offs.

Signed-off-by: xiaofanluan <xf@hjjaq.com>
Co-authored-by: xiaofanluan <xf@hjjaq.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-20 22:34:42 +08:00

398 lines
9.1 KiB
Go

package proxy
import (
"context"
"github.com/milvus-io/milvus-proto/go-api/v3/commonpb"
"github.com/milvus-io/milvus-proto/go-api/v3/milvuspb"
"github.com/milvus-io/milvus/internal/types"
"github.com/milvus-io/milvus/pkg/v3/common"
"github.com/milvus-io/milvus/pkg/v3/mlog"
"github.com/milvus-io/milvus/pkg/v3/proto/rootcoordpb"
"github.com/milvus-io/milvus/pkg/v3/util/commonpbutil"
"github.com/milvus-io/milvus/pkg/v3/util/funcutil"
"github.com/milvus-io/milvus/pkg/v3/util/merr"
"github.com/milvus-io/milvus/pkg/v3/util/paramtable"
"github.com/milvus-io/milvus/pkg/v3/util/timestamptz"
)
type createDatabaseTask struct {
baseTask
Condition
*milvuspb.CreateDatabaseRequest
ctx context.Context
mixCoord types.MixCoordClient
result *commonpb.Status
}
func (cdt *createDatabaseTask) TraceCtx() context.Context {
return cdt.ctx
}
func (cdt *createDatabaseTask) ID() UniqueID {
return cdt.Base.MsgID
}
func (cdt *createDatabaseTask) SetID(uid UniqueID) {
cdt.Base.MsgID = uid
}
func (cdt *createDatabaseTask) Name() string {
return CreateDatabaseTaskName
}
func (cdt *createDatabaseTask) Type() commonpb.MsgType {
return cdt.Base.MsgType
}
func (cdt *createDatabaseTask) BeginTs() Timestamp {
return cdt.Base.Timestamp
}
func (cdt *createDatabaseTask) EndTs() Timestamp {
return cdt.Base.Timestamp
}
func (cdt *createDatabaseTask) SetTs(ts Timestamp) {
cdt.Base.Timestamp = ts
}
func (cdt *createDatabaseTask) OnEnqueue() error {
if cdt.Base == nil {
cdt.Base = commonpbutil.NewMsgBase()
}
cdt.Base.MsgType = commonpb.MsgType_CreateDatabase
cdt.Base.SourceID = paramtable.GetNodeID()
return nil
}
func (cdt *createDatabaseTask) PreExecute(ctx context.Context) error {
err := ValidateDatabaseName(cdt.GetDbName())
if err != nil {
return err
}
tz, exist := funcutil.TryGetAttrByKeyFromRepeatedKV(common.TimezoneKey, cdt.GetProperties())
if exist && !timestamptz.IsTimezoneValid(tz) {
return merr.WrapErrParameterInvalidMsg("unknown or invalid IANA Time Zone ID: %s", tz)
}
return nil
}
func (cdt *createDatabaseTask) Execute(ctx context.Context) error {
var err error
cdt.result, err = cdt.mixCoord.CreateDatabase(ctx, cdt.CreateDatabaseRequest)
err = merr.CheckRPCCall(cdt.result, err)
return err
}
func (cdt *createDatabaseTask) PostExecute(ctx context.Context) error {
return nil
}
type dropDatabaseTask struct {
baseTask
Condition
*milvuspb.DropDatabaseRequest
ctx context.Context
mixCoord types.MixCoordClient
result *commonpb.Status
}
func (ddt *dropDatabaseTask) TraceCtx() context.Context {
return ddt.ctx
}
func (ddt *dropDatabaseTask) ID() UniqueID {
return ddt.Base.MsgID
}
func (ddt *dropDatabaseTask) SetID(uid UniqueID) {
ddt.Base.MsgID = uid
}
func (ddt *dropDatabaseTask) Name() string {
return DropCollectionTaskName
}
func (ddt *dropDatabaseTask) Type() commonpb.MsgType {
return ddt.Base.MsgType
}
func (ddt *dropDatabaseTask) BeginTs() Timestamp {
return ddt.Base.Timestamp
}
func (ddt *dropDatabaseTask) EndTs() Timestamp {
return ddt.Base.Timestamp
}
func (ddt *dropDatabaseTask) SetTs(ts Timestamp) {
ddt.Base.Timestamp = ts
}
func (ddt *dropDatabaseTask) OnEnqueue() error {
if ddt.Base == nil {
ddt.Base = commonpbutil.NewMsgBase()
}
ddt.Base.MsgType = commonpb.MsgType_DropDatabase
ddt.Base.SourceID = paramtable.GetNodeID()
return nil
}
func (ddt *dropDatabaseTask) PreExecute(ctx context.Context) error {
return ValidateDatabaseName(ddt.GetDbName())
}
func (ddt *dropDatabaseTask) Execute(ctx context.Context) error {
var err error
ddt.result, err = ddt.mixCoord.DropDatabase(ctx, ddt.DropDatabaseRequest)
err = merr.CheckRPCCall(ddt.result, err)
if err == nil {
// Local best-effort cleanup on the issuing proxy; the authoritative
// eviction is the DropDatabase broadcast handled in
// InvalidateCollectionMetaCache.
globalMetaCache.RemoveDatabase(ctx, ddt.DbName)
}
return err
}
func (ddt *dropDatabaseTask) PostExecute(ctx context.Context) error {
return nil
}
type listDatabaseTask struct {
baseTask
Condition
*milvuspb.ListDatabasesRequest
ctx context.Context
mixCoord types.MixCoordClient
result *milvuspb.ListDatabasesResponse
}
func (ldt *listDatabaseTask) TraceCtx() context.Context {
return ldt.ctx
}
func (ldt *listDatabaseTask) ID() UniqueID {
return ldt.Base.MsgID
}
func (ldt *listDatabaseTask) SetID(uid UniqueID) {
ldt.Base.MsgID = uid
}
func (ldt *listDatabaseTask) Name() string {
return ListDatabaseTaskName
}
func (ldt *listDatabaseTask) Type() commonpb.MsgType {
return ldt.Base.MsgType
}
func (ldt *listDatabaseTask) BeginTs() Timestamp {
return ldt.Base.Timestamp
}
func (ldt *listDatabaseTask) EndTs() Timestamp {
return ldt.Base.Timestamp
}
func (ldt *listDatabaseTask) SetTs(ts Timestamp) {
ldt.Base.Timestamp = ts
}
func (ldt *listDatabaseTask) OnEnqueue() error {
ldt.Base = commonpbutil.NewMsgBase()
ldt.Base.MsgType = commonpb.MsgType_ListDatabases
ldt.Base.SourceID = paramtable.GetNodeID()
return nil
}
func (ldt *listDatabaseTask) PreExecute(ctx context.Context) error {
return nil
}
func (ldt *listDatabaseTask) Execute(ctx context.Context) error {
var err error
ctx = AppendUserInfoForRPC(ctx)
ldt.result, err = ldt.mixCoord.ListDatabases(ctx, ldt.ListDatabasesRequest)
return merr.CheckRPCCall(ldt.result, err)
}
func (ldt *listDatabaseTask) PostExecute(ctx context.Context) error {
return nil
}
type alterDatabaseTask struct {
baseTask
Condition
*milvuspb.AlterDatabaseRequest
ctx context.Context
mixCoord types.MixCoordClient
result *commonpb.Status
}
func (t *alterDatabaseTask) TraceCtx() context.Context {
return t.ctx
}
func (t *alterDatabaseTask) ID() UniqueID {
return t.Base.MsgID
}
func (t *alterDatabaseTask) SetID(uid UniqueID) {
t.Base.MsgID = uid
}
func (t *alterDatabaseTask) Name() string {
return AlterDatabaseTaskName
}
func (t *alterDatabaseTask) Type() commonpb.MsgType {
return t.Base.MsgType
}
func (t *alterDatabaseTask) BeginTs() Timestamp {
return t.Base.Timestamp
}
func (t *alterDatabaseTask) EndTs() Timestamp {
return t.Base.Timestamp
}
func (t *alterDatabaseTask) SetTs(ts Timestamp) {
t.Base.Timestamp = ts
}
func (t *alterDatabaseTask) OnEnqueue() error {
if t.Base == nil {
t.Base = commonpbutil.NewMsgBase()
}
t.Base.MsgType = commonpb.MsgType_AlterDatabase
t.Base.SourceID = paramtable.GetNodeID()
return nil
}
func (t *alterDatabaseTask) PreExecute(ctx context.Context) error {
if len(t.GetProperties()) > 0 {
// Check the validation of timezone
userDefinedTimezone, exist := funcutil.TryGetAttrByKeyFromRepeatedKV(common.TimezoneKey, t.Properties)
if exist && !timestamptz.IsTimezoneValid(userDefinedTimezone) {
return merr.WrapErrParameterInvalidMsg("unknown or invalid IANA Time Zone ID: %s", userDefinedTimezone)
}
}
return nil
}
func (t *alterDatabaseTask) Execute(ctx context.Context) error {
var err error
req := &rootcoordpb.AlterDatabaseRequest{
Base: t.GetBase(),
DbName: t.GetDbName(),
DbId: t.GetDbId(),
Properties: t.GetProperties(),
DeleteKeys: t.GetDeleteKeys(),
}
ret, err := t.mixCoord.AlterDatabase(ctx, req)
err = merr.CheckRPCCall(ret, err)
if err != nil {
return err
}
t.result = ret
return nil
}
func (t *alterDatabaseTask) PostExecute(ctx context.Context) error {
return nil
}
type describeDatabaseTask struct {
baseTask
Condition
*milvuspb.DescribeDatabaseRequest
ctx context.Context
mixCoord types.MixCoordClient
result *milvuspb.DescribeDatabaseResponse
}
func (t *describeDatabaseTask) TraceCtx() context.Context {
return t.ctx
}
func (t *describeDatabaseTask) ID() UniqueID {
return t.Base.MsgID
}
func (t *describeDatabaseTask) SetID(uid UniqueID) {
t.Base.MsgID = uid
}
func (t *describeDatabaseTask) Name() string {
return AlterDatabaseTaskName
}
func (t *describeDatabaseTask) Type() commonpb.MsgType {
return t.Base.MsgType
}
func (t *describeDatabaseTask) BeginTs() Timestamp {
return t.Base.Timestamp
}
func (t *describeDatabaseTask) EndTs() Timestamp {
return t.Base.Timestamp
}
func (t *describeDatabaseTask) SetTs(ts Timestamp) {
t.Base.Timestamp = ts
}
func (t *describeDatabaseTask) OnEnqueue() error {
if t.Base == nil {
t.Base = commonpbutil.NewMsgBase()
}
t.Base.MsgType = commonpb.MsgType_DescribeDatabase
t.Base.SourceID = paramtable.GetNodeID()
return nil
}
func (t *describeDatabaseTask) PreExecute(ctx context.Context) error {
return nil
}
func (t *describeDatabaseTask) Execute(ctx context.Context) error {
req := &rootcoordpb.DescribeDatabaseRequest{
Base: t.GetBase(),
DbName: t.GetDbName(),
}
ctx = AppendUserInfoForRPC(ctx)
ret, err := t.mixCoord.DescribeDatabase(ctx, req)
if err != nil {
mlog.Warn(ctx, "DescribeDatabase failed", mlog.Err(err))
return err
}
if err := merr.CheckRPCCall(ret, err); err != nil {
mlog.Warn(ctx, "DescribeDatabase failed", mlog.Err(err))
return err
}
t.result = &milvuspb.DescribeDatabaseResponse{
Status: ret.GetStatus(),
DbName: ret.GetDbName(),
DbID: ret.GetDbID(),
CreatedTimestamp: ret.GetCreatedTimestamp(),
Properties: ret.GetProperties(),
}
return nil
}
func (t *describeDatabaseTask) PostExecute(ctx context.Context) error {
return nil
}