Files
Enterprise-Knowledge-Base/internal/application/service/retriever/factory.go
T
ochan.kwon 0e8de6192c feat(knowledge-base): validate vector store bindings on create, copy, and delete
Wires KnowledgeBase.VectorStoreID and the ownership-aware retrieve factory
into the user-facing knowledge-base lifecycle:

- POST /knowledge-bases validates the requested vector_store_id against
  the caller's tenant scope and the engine registry. New error codes
  ErrVectorStoreBindingInvalid (2200) and ErrVectorStoreUnavailable (2201)
  distinguish the typed branches without echoing UUIDs to the client.
- GET / POST / PUT / PUT-pin responses embed the bound store's display
  metadata (name, source, engine_type, status) without exposing any
  connection credentials. Cross-tenant shared KBs receive a suppressed
  payload (vector_store_id stripped, source="shared") so operator-chosen
  store names cannot be enumerated across tenants.
- POST /knowledge-bases/copy synchronously rejects clones whose target
  has a different embedding model or vector store, before the async
  clone task is enqueued. The async clone worker re-applies the same
  checks for defense in depth.
- DELETE /vector-stores/:id refuses to remove a store with bound KBs,
  inside a transaction that row-locks the store on PostgreSQL and
  serializes via WAL on SQLite. unregister-from-registry is wrapped in
  defer/recover so a panic surfaces as a structured warning instead of
  silently leaking a stale engine.
- vector_store_id is immutable after creation. The GORM <-:create tag
  blocks every ORM update path; the service-layer DTO omits the field
  entirely; a reflection-based regression test catches any future
  maintainer who adds it back to either layer.
- Empty-string vector_store_id is normalized to nil at both the create
  path and inside SharesStoreWith, so rows persisted by callers that
  did not run Normalize first cannot trip false same-store comparisons.

Part of #993. Depends on #994 and #1310.
2026-05-18 15:58:46 +08:00

215 lines
8.4 KiB
Go

package retriever
import (
"context"
"errors"
"slices"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
)
// Sentinel errors returned by factory functions. Callers may use errors.Is to
// classify. User-facing responses MUST wrap or replace these with generic
// messages — the sentinels intentionally omit store UUIDs to avoid enumeration
// leaks. Structured logs inside the factory record the tenant/store IDs.
var (
// ErrTenantInfoMissing is returned when the factory needs a tenant from
// context (synchronous, unbound KB path) and none is present.
ErrTenantInfoMissing = errors.New("tenant info not found in context")
// ErrVectorStoreNotFound is returned when the store ID is not registered
// (or an internal lookup for ownership failed). Async workers should treat
// this as non-retryable.
ErrVectorStoreNotFound = errors.New("vector store not available")
// ErrVectorStoreForbidden is returned when the resolved store is not
// owned by the given tenant. This guards against cross-tenant access
// in case the upstream validation layer has a gap. Async workers should
// treat this as non-retryable.
ErrVectorStoreForbidden = errors.New("vector store access denied")
)
// TenantStoreOwnership abstracts the lookup used by factory functions to
// verify that a given vector store ID is owned by the given tenant ID.
//
// Production implementations wrap the VectorStoreRepository; tests inject
// in-memory fakes so they can cover the ownership branches without touching
// a database.
type TenantStoreOwnership interface {
// StoreOwnedBy reports whether the store with the given ID is owned
// by the given tenant. When the store does not exist, it returns
// (false, nil). Errors are reserved for infrastructure failures such as
// database connectivity issues.
StoreOwnedBy(ctx context.Context, storeID string, tenantID uint64) (bool, error)
}
// VerifyBinding asserts that a non-empty storeID is owned by tenantID and
// registered in the in-memory engine registry. It encapsulates the two
// checks that gate every store-bound resolution so that callers outside
// the retriever package (notably the KB create-validation path) can reuse
// the same sentinel hierarchy instead of duplicating the logic.
//
// Resolution rules:
//
// - ownership.StoreOwnedBy returns an infrastructure error → that error
// is returned verbatim so callers can decide retry/abort.
// - ownership returns (false, nil) → ErrVectorStoreForbidden.
// - ownership returns (true, nil) + registry.GetByStoreID fails →
// ErrVectorStoreNotFound.
// - all checks succeed → nil.
//
// VerifyBinding itself never echoes the store UUID; callers MUST wrap the
// sentinels into user-facing errors at the boundary (and log the
// tenant/store pair via structured fields when appropriate).
//
// resolveBoundEngine (below) intentionally does NOT delegate to VerifyBinding
// because it also needs the resolved engine service; sharing would require
// either a second registry lookup or returning the service from VerifyBinding,
// both of which dilute the helper's single purpose. The two paths are kept
// in lockstep by the factory_test.go matrix.
func VerifyBinding(
ctx context.Context,
registry interfaces.RetrieveEngineRegistry,
ownership TenantStoreOwnership,
tenantID uint64,
storeID string,
) error {
owned, err := ownership.StoreOwnedBy(ctx, storeID, tenantID)
if err != nil {
return err
}
if !owned {
return ErrVectorStoreForbidden
}
if _, err := registry.GetByStoreID(storeID); err != nil {
return ErrVectorStoreNotFound
}
return nil
}
// CreateRetrieveEngineForKB returns a CompositeRetrieveEngine resolved from
// a KB's VectorStore binding.
//
// Resolution rules:
//
// - vectorStoreID == nil || *vectorStoreID == "" →
// falls back to the tenant's effective engines (env-store flow driven
// by RETRIEVE_DRIVER). TenantInfo is read from ctx.
// - otherwise →
// 1) ownership.StoreOwnedBy(*storeID, tenantID) must return true;
// cross-tenant attempts yield ErrVectorStoreForbidden.
// 2) registry.GetByStoreID(*storeID) must succeed;
// unregistered stores yield ErrVectorStoreNotFound.
// 3) the single engine is wrapped by NewCompositeRetrieveEngine so
// that its Support()-based retriever-type matching is preserved.
//
// Use this for 23 synchronous call sites across the application services.
// Async task handlers that cannot rely on ctx-based TenantInfo (currently:
// ProcessKBDeleteTask, ProcessIndexDelete) must use
// CreateRetrieveEngineFromPayload instead.
func CreateRetrieveEngineForKB(
ctx context.Context,
registry interfaces.RetrieveEngineRegistry,
ownership TenantStoreOwnership,
tenantID uint64,
vectorStoreID *string,
) (*CompositeRetrieveEngine, error) {
// Normalize nil and empty-string pointer to "unbound" so that callers
// cannot accidentally route an empty UUID into GetByStoreID.
if vectorStoreID == nil || *vectorStoreID == "" {
tenantInfo, ok := types.TenantInfoFromContext(ctx)
if !ok {
return nil, ErrTenantInfoMissing
}
return NewCompositeRetrieveEngine(registry, tenantInfo.GetEffectiveEngines())
}
return resolveBoundEngine(ctx, registry, ownership, tenantID, *vectorStoreID)
}
// CreateRetrieveEngineFromPayload is the async-task variant. It does not
// read TenantInfo from ctx because async handlers do not populate it.
// Instead, tenantID is passed explicitly from the deserialized payload and
// is verified against the store's tenant when vectorStoreID is non-empty.
//
// Tasks enqueued before vectorStoreID was added to the payload decode it as
// nil and transparently fall back to the pre-serialized effectiveEngines
// path — no in-flight task is lost across upgrades.
func CreateRetrieveEngineFromPayload(
ctx context.Context,
registry interfaces.RetrieveEngineRegistry,
ownership TenantStoreOwnership,
tenantID uint64,
effectiveEngines []types.RetrieverEngineParams,
vectorStoreID *string,
) (*CompositeRetrieveEngine, error) {
if vectorStoreID == nil || *vectorStoreID == "" {
return NewCompositeRetrieveEngine(registry, effectiveEngines)
}
return resolveBoundEngine(ctx, registry, ownership, tenantID, *vectorStoreID)
}
// resolveBoundEngine is the shared ownership-verified lookup path used by
// both CreateRetrieveEngineForKB and CreateRetrieveEngineFromPayload. It
// returns sentinel errors so that handlers can classify them (for example,
// async workers convert Forbidden/NotFound into asynq.SkipRetry).
func resolveBoundEngine(
ctx context.Context,
registry interfaces.RetrieveEngineRegistry,
ownership TenantStoreOwnership,
tenantID uint64,
storeID string,
) (*CompositeRetrieveEngine, error) {
owned, err := ownership.StoreOwnedBy(ctx, storeID, tenantID)
if err != nil {
// Infrastructure failure — record the raw error for operators but
// do not leak internals to the caller.
logger.ErrorWithFields(ctx, err, map[string]interface{}{
"tenant_id": tenantID,
"store_id": storeID,
"reason": "ownership lookup failed",
})
return nil, ErrVectorStoreNotFound
}
if !owned {
// Cross-tenant attempt (or the store has been deleted in the
// meantime). Log with WARN so that audits can surface probing.
logger.Warnf(ctx,
"[retriever.factory] cross-tenant store access attempted: tenant=%d store=%s",
tenantID, storeID)
return nil, ErrVectorStoreForbidden
}
svc, err := registry.GetByStoreID(storeID)
if err != nil {
logger.ErrorWithFields(ctx, err, map[string]interface{}{
"tenant_id": tenantID,
"store_id": storeID,
"reason": "store not registered",
})
return nil, ErrVectorStoreNotFound
}
// Build the composite directly from the resolved service.
//
// We cannot delegate to NewCompositeRetrieveEngine here because that
// function resolves engines through registry.GetRetrieveEngineService,
// which reads from the byEngineType map (env stores). DB stores live
// in the byStoreID map and are not reachable via engine type alone —
// multiple stores can share the same engine type.
//
// Semantics: a KB bound to a DB store uses every retriever type that
// store supports. This intentionally overrides the tenant-level
// effective-engines filter, because binding a KB to a specific store
// is an explicit opt-out of tenant-default routing.
return &CompositeRetrieveEngine{
engineInfos: []*engineInfo{{
retrieveEngine: svc,
retrieverType: slices.Clone(svc.Support()),
}},
}, nil
}