feat(client): split WithToken, add Raw + auth helpers (PR-2)

Five additive SDK changes that PR-3 (CLI Factory adapter) and PR-4
(auth login / status) consume.

WithToken split (Breaking + alias):
- WithAPIKey(key) sets X-API-Key header (long-lived API keys)
- WithBearerToken(token) sets Authorization: Bearer header (JWTs)
- WithToken kept as deprecated alias for WithAPIKey for two minor versions
- doRequest now sets X-API-Key and Authorization headers independently;
  callers can carry both kinds of credentials simultaneously

applyAuthHeaders extraction:
- Header injection (X-API-Key, Authorization, X-Request-ID, X-Tenant-ID)
  is now a Client method shared between doRequest and the multipart path
  in CreateKnowledgeFromFile. Eliminates ~30 lines of drift risk and
  fixes the latent missing X-Tenant-ID on file uploads.
- Drops the dead second tenant-header switch in doRequest.

Raw escape hatch:
- Client.Raw(ctx, method, path, body) is the public passthrough used by
  the future \`weknora api\` command. godoc marks it experimental.

Auth methods (auth.go, new):
- Login(ctx, LoginRequest) -> POST /auth/login (existing server endpoint)
- GetCurrentUser(ctx) -> GET /auth/me, returns *CurrentUserResponse
- RefreshToken(ctx, refreshToken) -> POST /auth/refresh
- Types: LoginRequest, LoginResponse, AuthUser, AuthTenant,
  CurrentUserResponse, RefreshTokenResponse

No server changes. The auth methods consume endpoints that already exist;
PR-3/PR-4 wire them through the CLI.
This commit is contained in:
nullkey
2026-05-06 14:22:53 +08:00
committed by lyingbug
parent a39805aa89
commit 37d4fbde5d
4 changed files with 225 additions and 51 deletions
+117
View File
@@ -0,0 +1,117 @@
package client
import (
"context"
"fmt"
"net/http"
"time"
)
// LoginRequest is the body for POST /api/v1/auth/login.
type LoginRequest struct {
Email string `json:"email"`
Password string `json:"password"`
}
// LoginResponse is the body returned by POST /api/v1/auth/login.
//
// Token is the JWT access token; RefreshToken renews it via Auth.Refresh.
type LoginResponse struct {
Success bool `json:"success"`
Message string `json:"message,omitempty"`
User *AuthUser `json:"user,omitempty"`
Tenant *AuthTenant `json:"tenant,omitempty"`
Token string `json:"token,omitempty"`
RefreshToken string `json:"refresh_token,omitempty"`
}
// AuthUser is the principal returned by /auth/login and /auth/me.
//
// Fields mirror the server's UserInfo projection (no PasswordHash).
type AuthUser struct {
ID string `json:"id"`
Username string `json:"username"`
Email string `json:"email"`
Avatar string `json:"avatar,omitempty"`
TenantID uint64 `json:"tenant_id"`
IsActive bool `json:"is_active"`
CanAccessAllTenants bool `json:"can_access_all_tenants,omitempty"`
CreatedAt time.Time `json:"created_at,omitempty"`
}
// AuthTenant is the tenant projection returned alongside AuthUser.
type AuthTenant struct {
ID uint64 `json:"id"`
Name string `json:"name"`
}
// CurrentUserResponse is the body of GET /api/v1/auth/me.
type CurrentUserResponse struct {
Success bool `json:"success"`
Data struct {
User *AuthUser `json:"user,omitempty"`
Tenant *AuthTenant `json:"tenant,omitempty"`
} `json:"data"`
}
// RefreshTokenResponse is the body of POST /api/v1/auth/refresh.
type RefreshTokenResponse struct {
Success bool `json:"success"`
Message string `json:"message,omitempty"`
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
}
// Login authenticates with email + password and returns the JWT access token,
// refresh token, and principal info. Maps to POST /api/v1/auth/login.
//
// Used by `weknora auth login`.
func (c *Client) Login(ctx context.Context, req LoginRequest) (*LoginResponse, error) {
resp, err := c.doRequest(ctx, http.MethodPost, "/api/v1/auth/login", req, nil)
if err != nil {
return nil, fmt.Errorf("login request: %w", err)
}
var out LoginResponse
if err := parseResponse(resp, &out); err != nil {
return nil, err
}
return &out, nil
}
// GetCurrentUser returns the currently authenticated principal and the
// tenant projection. Maps to GET /api/v1/auth/me; the bearer token must
// already be set on the client (use WithBearerToken).
//
// Used by `weknora auth status` and `weknora whoami`.
func (c *Client) GetCurrentUser(ctx context.Context) (*CurrentUserResponse, error) {
resp, err := c.doRequest(ctx, http.MethodGet, "/api/v1/auth/me", nil, nil)
if err != nil {
return nil, fmt.Errorf("get current user: %w", err)
}
var out CurrentUserResponse
if err := parseResponse(resp, &out); err != nil {
return nil, err
}
return &out, nil
}
// RefreshToken renews the JWT access token using a refresh token.
// Maps to POST /api/v1/auth/refresh.
//
// Callers (`weknora auth refresh`) read the refresh token from secrets,
// invoke this method, and persist both new tokens. The SDK does not touch
// the secrets store directly — it stays a transport-only layer.
func (c *Client) RefreshToken(ctx context.Context, refreshToken string) (*RefreshTokenResponse, error) {
body := struct {
RefreshToken string `json:"refreshToken"`
}{RefreshToken: refreshToken}
resp, err := c.doRequest(ctx, http.MethodPost, "/api/v1/auth/refresh", body, nil)
if err != nil {
return nil, fmt.Errorf("refresh token: %w", err)
}
var out RefreshTokenResponse
if err := parseResponse(resp, &out); err != nil {
return nil, err
}
return &out, nil
}
+73 -41
View File
@@ -14,12 +14,21 @@ import (
"time"
)
// Client is the client for interacting with the WeKnora service
// Client is the client for interacting with the WeKnora service.
//
// Authentication uses one of two credential kinds:
// - API key (long-lived, set via X-API-Key) — see WithAPIKey
// - Bearer JWT (short-lived, set via Authorization)— see WithBearerToken
//
// Both may be configured simultaneously; X-API-Key takes precedence at the
// HTTP layer. The legacy WithToken is kept as an alias for WithAPIKey for two
// minor versions of compatibility.
type Client struct {
baseURL string
httpClient *http.Client
token string
tenantID *uint64
baseURL string
httpClient *http.Client
apiKey string
bearerToken string
tenantID *uint64
}
// ClientOption defines client configuration options
@@ -32,15 +41,39 @@ func WithTimeout(timeout time.Duration) ClientOption {
}
}
// WithToken sets the authentication token
func WithToken(token string) ClientOption {
// WithAPIKey sets the long-lived API key sent as the X-API-Key header.
func WithAPIKey(key string) ClientOption {
return func(c *Client) {
c.token = token
c.apiKey = key
}
}
// WithTenantID sets the tenant ID that will be included in requests as the X-Tenant-ID header.
// It can be overridden per-request by setting the "TenantID" value in the request context.
// WithBearerToken sets the JWT bearer token sent as the Authorization header.
// Used after a successful auth.login to call authenticated endpoints with the
// short-lived access token.
func WithBearerToken(token string) ClientOption {
return func(c *Client) {
c.bearerToken = token
}
}
// WithToken is the v0.x compatibility alias for WithAPIKey. Prefer WithAPIKey
// (or WithBearerToken for JWT). Will be removed in the next major; the alias
// is preserved for two minor versions per ADR.
//
// Deprecated: use WithAPIKey for X-API-Key, WithBearerToken for JWT.
func WithToken(token string) ClientOption {
return WithAPIKey(token)
}
// WithTenantID sets X-Tenant-ID on every request. Use only for explicit
// cross-tenant access by callers with CanAccessAllTenants — the server's
// auth middleware runs the cross-tenant gate whenever this header is
// present on a bearer request, even when the value matches the credential's
// own tenant, and 403s normal users. JWT bearer tokens and tenant-scoped
// API keys carry tenant identity intrinsically, so the header is redundant
// (and harmful) for default-tenant traffic. Per-request override via the
// "TenantID" context value still applies.
func WithTenantID(tenantID uint64) ClientOption {
return func(c *Client) {
c.tenantID = &tenantID
@@ -87,16 +120,29 @@ func (c *Client) doRequest(ctx context.Context,
}
req.Header.Set("Content-Type", "application/json")
if c.token != "" {
req.Header.Set("X-API-Key", c.token)
c.applyAuthHeaders(ctx, req)
return c.httpClient.Do(req)
}
// applyAuthHeaders sets X-API-Key, Authorization, X-Request-ID, and X-Tenant-ID
// on req based on client config and ctx values. Used by doRequest and any
// caller that builds its own *http.Request (currently CreateKnowledgeFromFile,
// which uses multipart and can't go through doRequest).
func (c *Client) applyAuthHeaders(ctx context.Context, req *http.Request) {
if c.apiKey != "" {
req.Header.Set("X-API-Key", c.apiKey)
}
if c.bearerToken != "" {
req.Header.Set("Authorization", "Bearer "+c.bearerToken)
}
if requestID := ctx.Value("RequestID"); requestID != nil {
req.Header.Set("X-Request-ID", requestID.(string))
if s, ok := requestID.(string); ok {
req.Header.Set("X-Request-ID", s)
}
}
// Tenant header: prefer per-request context value, fall back to client-level tenantID
tenantID := c.tenantID
if ctxTenant := ctx.Value("TenantID"); ctxTenant != nil {
switch v := ctxTenant.(type) {
case *uint64:
@@ -104,41 +150,27 @@ func (c *Client) doRequest(ctx context.Context,
tenantID = v
}
case uint64:
tmp := v
tenantID = &tmp
tenantID = &v
case string:
if parsed, err := strconv.ParseUint(v, 10, 64); err == nil {
tmp := parsed
tenantID = &tmp
tenantID = &parsed
}
}
}
// 2) Fallback: plain string key "TenantID" (some callers may use this)
if tenantID == nil {
if ctxTenant := ctx.Value("TenantID"); ctxTenant != nil {
switch v := ctxTenant.(type) {
case *uint64:
if v != nil {
tenantID = v
}
case uint64:
tmp := v
tenantID = &tmp
case string:
if parsed, err := strconv.ParseUint(v, 10, 64); err == nil {
tmp := parsed
tenantID = &tmp
}
}
}
}
if tenantID != nil {
req.Header.Set("X-Tenant-ID", strconv.FormatUint(*tenantID, 10))
}
}
return c.httpClient.Do(req)
// Raw performs a raw HTTP request against the WeKnora API with the client's
// auth headers, X-Request-ID, and X-Tenant-ID injection applied.
//
// Experimental: this method is intended for one-off integrations and the
// `weknora api` CLI passthrough. The signature, return type, and behavior may
// change in any minor version. Prefer typed methods (ListKnowledgeBases,
// GetKnowledgeBase, etc.) when they exist.
func (c *Client) Raw(ctx context.Context, method, path string, body interface{}) (*http.Response, error) {
return c.doRequest(ctx, method, path, body, nil)
}
// parseResponse parses an HTTP response
+1 -7
View File
@@ -164,14 +164,8 @@ func (c *Client) CreateKnowledgeFromFile(ctx context.Context,
return nil, fmt.Errorf("failed to close writer: %w", err)
}
// Set request headers
req.Header.Set("Content-Type", writer.FormDataContentType())
if c.token != "" {
req.Header.Set("X-API-Key", c.token)
}
if requestID := ctx.Value("RequestID"); requestID != nil {
req.Header.Set("X-Request-ID", requestID.(string))
}
c.applyAuthHeaders(ctx, req)
// Set the request body
req.Body = io.NopCloser(body)
+34 -3
View File
@@ -138,7 +138,37 @@ type KnowledgeBaseListResponse struct {
Data []KnowledgeBase `json:"data"`
}
// SearchResult represents search result
// MatchType records which retrieval channel produced a SearchResult.
// Numeric values are the wire contract; they mirror the iota order in
// server-side internal/types/embedding.go — do not reorder without
// coordinating a server bump. Server-side names are preserved as
// trailing comments so cross-repo grep works in both directions.
//
// Channel grouping: 0-1 primary text channels (vector + keyword);
// 2-5 enrichment chunks (added in addition to primary matches, score=0);
// 6-9 alternate sources (graph DB, web search, raw load, data analysis).
type MatchType int
const (
MatchTypeVector MatchType = 0 // server: MatchTypeEmbedding
MatchTypeKeyword MatchType = 1 // server: MatchTypeKeywords
MatchTypeNearby MatchType = 2 // server: MatchTypeNearByChunk
MatchTypeHistory MatchType = 3 // server: MatchTypeHistory
MatchTypeParent MatchType = 4 // server: MatchTypeParentChunk
MatchTypeRelation MatchType = 5 // server: MatchTypeRelationChunk
MatchTypeGraph MatchType = 6 // server: MatchTypeGraph
MatchTypeWeb MatchType = 7 // server: MatchTypeWebSearch
MatchTypeDirect MatchType = 8 // server: MatchTypeDirectLoad — chunk loaded by ID without scoring
MatchTypeData MatchType = 9 // server: MatchTypeDataAnalysis — produced by analytical pipeline, not retrieval
)
// SearchResult represents search result.
//
// Score is the RRF (reciprocal-rank-fusion) score combining vector and
// keyword channels — typically in the [0, ~0.03] range when both channels
// hit, NOT the raw vector similarity. Use MatchType to tell which channel
// produced each result. Per-channel thresholds (vector_threshold,
// keyword_threshold) filter pre-fusion at retrieval time, before RRF runs.
type SearchResult struct {
ID string `json:"id"`
Content string `json:"content"`
@@ -149,12 +179,13 @@ type SearchResult struct {
EndAt int `json:"end_at"`
Seq int `json:"seq"`
Score float64 `json:"score"`
MatchType MatchType `json:"match_type"`
ChunkType string `json:"chunk_type"`
ImageInfo string `json:"image_info"`
Metadata map[string]string `json:"metadata"`
KnowledgeFilename string `json:"knowledge_filename"`
KnowledgeSource string `json:"knowledge_source"`
KnowledgeChannel string `json:"knowledge_channel"`
KnowledgeSource string `json:"knowledge_source"`
KnowledgeChannel string `json:"knowledge_channel"`
// MatchedContent is the actual content that was matched in vector search
// For FAQ: this is the matched question text (standard or similar question)
MatchedContent string `json:"matched_content,omitempty"`