88 lines
2.9 KiB
Go
88 lines
2.9 KiB
Go
package dobotaiops
|
||
|
||
import (
|
||
"encoding/base64"
|
||
"fmt"
|
||
"strings"
|
||
"time"
|
||
)
|
||
|
||
// Window 是一次只读统计/列举的时间范围,语义固定为**半开区间**:
|
||
// created_at >= Start AND created_at < End(工单要求)。
|
||
type Window struct {
|
||
TenantKey string
|
||
Start time.Time
|
||
End time.Time
|
||
}
|
||
|
||
// NewWindow 解析并校验调用方给的租户与时间范围:
|
||
// - 租户非空、长度受限(不做任何 SQL 拼接,只作为绑定参数);
|
||
// - 时间是 RFC3339(允许带时区),必须有 start < end;
|
||
// - 窗口跨度不超过上限(默认 90 天)、不允许跑到未来太远。
|
||
func NewWindow(tenantKey, startRaw, endRaw string, limit time.Duration, now time.Time) (Window, error) {
|
||
tenantKey = strings.TrimSpace(tenantKey)
|
||
if tenantKey == "" || len(tenantKey) > 128 {
|
||
return Window{}, fmt.Errorf("%w: tenant key is required", ErrInvalidQuery)
|
||
}
|
||
start, err := parseInstant(startRaw)
|
||
if err != nil {
|
||
return Window{}, err
|
||
}
|
||
end, err := parseInstant(endRaw)
|
||
if err != nil {
|
||
return Window{}, err
|
||
}
|
||
if !start.Before(end) {
|
||
return Window{}, fmt.Errorf("%w: start must be before end", ErrInvalidQuery)
|
||
}
|
||
if limit <= 0 {
|
||
limit = 90 * 24 * time.Hour
|
||
}
|
||
if end.Sub(start) > limit {
|
||
return Window{}, fmt.Errorf("%w: window exceeds the %s limit", ErrInvalidQuery, limit)
|
||
}
|
||
if end.After(now.Add(5 * time.Minute)) {
|
||
return Window{}, fmt.Errorf("%w: end is in the future", ErrInvalidQuery)
|
||
}
|
||
return Window{TenantKey: tenantKey, Start: start.UTC(), End: end.UTC()}, nil
|
||
}
|
||
|
||
func parseInstant(raw string) (time.Time, error) {
|
||
raw = strings.TrimSpace(raw)
|
||
if raw == "" {
|
||
return time.Time{}, fmt.Errorf("%w: time is required", ErrInvalidQuery)
|
||
}
|
||
parsed, err := time.Parse(time.RFC3339, raw)
|
||
if err != nil {
|
||
return time.Time{}, fmt.Errorf("%w: time must be RFC3339 (with offset)", ErrInvalidQuery)
|
||
}
|
||
return parsed.UTC(), nil
|
||
}
|
||
|
||
// Cursor 是 (created_at, id) 复合游标:与工单要求一致 —— 稳定、确定性、翻页不漏不重。
|
||
type Cursor struct {
|
||
CreatedAt time.Time
|
||
ID string
|
||
}
|
||
|
||
// EncodeCursor / DecodeCursor 只做无损编解码,不做业务判断;非法游标一律报 ErrInvalidQuery。
|
||
func EncodeCursor(cursor Cursor) string {
|
||
return base64.RawURLEncoding.EncodeToString([]byte(cursor.CreatedAt.UTC().Format(time.RFC3339Nano) + "|" + cursor.ID))
|
||
}
|
||
|
||
func DecodeCursor(raw string) (Cursor, error) {
|
||
decoded, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(raw))
|
||
if err != nil {
|
||
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
|
||
}
|
||
parts := strings.SplitN(string(decoded), "|", 2)
|
||
if len(parts) != 2 || parts[1] == "" {
|
||
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
|
||
}
|
||
createdAt, err := time.Parse(time.RFC3339Nano, parts[0])
|
||
if err != nil {
|
||
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
|
||
}
|
||
return Cursor{CreatedAt: createdAt.UTC(), ID: parts[1]}, nil
|
||
}
|