feat(cloudflare): 支持分组级自动与手动 TTL 配置 (#62)

This commit is contained in:
Deqiying
2026-11-08 22:07:26 +08:00
committed by GitHub
parent 18dee29b73
commit e0ba758afa
23 changed files with 775 additions and 7 deletions
@@ -14,6 +14,7 @@ const (
errGroupTargetModeInvalid = "select a valid target mode"
errRecordTypeInvalid = "select a CNAME, A or AAAA record type"
errRecordContentInvalid = "invalid DNS record value; check the domain name or IP address"
errGroupTTLInvalid = "TTL must be 1 (automatic) or an integer between 60 and 86400 seconds"
errNodeInvalid = "select a valid edge node"
errNodeIPv4Required = "the active node requires a valid IPv4 address"
errGroupDisabled = "target group is disabled"
@@ -19,6 +19,13 @@ import (
"gorm.io/gorm"
)
const (
automaticTTL = 1
legacyDefaultTTL = 300
minManualTTL = 60
maxManualTTL = 86400
)
var clientFactory = func(token string) Client { return NewHTTPClient(token) }
// SetClientFactoryForTest replaces Cloudflare client construction for tests.
@@ -227,6 +234,16 @@ func groupFromInput(ctx context.Context, existing *model.CFPointingGroup, input
if targetMode != model.CFPointingTargetModeNode && targetMode != model.CFPointingTargetModeCustom {
return nil, errors.New(errGroupTargetModeInvalid)
}
ttl := automaticTTL
if existing != nil {
ttl = groupTTL(existing)
}
if input.TTL != nil {
ttl = *input.TTL
}
if ttl != automaticTTL && (ttl < minManualTTL || ttl > maxManualTTL) {
return nil, errors.New(errGroupTTLInvalid)
}
primaryNodeID := uint(0)
var backupNodeID *uint
recordType := strings.ToUpper(strings.TrimSpace(input.RecordType))
@@ -259,6 +276,7 @@ func groupFromInput(ctx context.Context, existing *model.CFPointingGroup, input
existing.TargetMode = targetMode
existing.RecordType = recordType
existing.RecordContent = recordContent
existing.TTL = ttl
existing.PrimaryNodeID = primaryNodeID
existing.ActiveNodeID = activeNodeID
existing.BackupNodeID = backupNodeID
@@ -267,6 +285,14 @@ func groupFromInput(ctx context.Context, existing *model.CFPointingGroup, input
return existing, nil
}
// groupTTL 保留升级前分组的 300 秒行为;数据库零值不直接发送给 Cloudflare。
func groupTTL(group *model.CFPointingGroup) int {
if group.TTL == 0 {
return legacyDefaultTTL
}
return group.TTL
}
func equalOptionalUint(left, right *uint) bool {
if left == nil || right == nil {
return left == right
@@ -419,6 +445,7 @@ func buildGroupItem(ctx context.Context, group *model.CFPointingGroup) (*GroupIt
return nil, err
}
item := &GroupItem{ID: group.ID, Name: group.Name, TargetMode: targetMode, RecordType: group.RecordType, RecordContent: group.RecordContent, PrimaryNode: nodeOptionForID(group.PrimaryNodeID, primary), ActiveNode: nodeOptionForID(group.ActiveNodeID, active), DefaultProxied: group.DefaultProxied, Enabled: group.Enabled, MemberCount: count, CreatedAt: group.CreatedAt, UpdatedAt: group.UpdatedAt}
item.TTL = groupTTL(group)
if group.BackupNodeID != nil {
backup, backupErr := lookupGroupNode(ctx, group.ID, *group.BackupNodeID)
if backupErr != nil {
@@ -76,9 +76,9 @@ func reconcileMember(ctx context.Context, memberID uint) error {
}
input.Name = state.Domain.Domain
input.Proxied = state.Member.Proxied
input.TTL = 300
input.TTL = groupTTL(&state.Group)
if input.Proxied {
input.TTL = 1
input.TTL = automaticTTL
}
recordID := state.Member.CFRecordID
if recordID != "" {
@@ -0,0 +1,255 @@
// Copyright 2026 Arctel.net
// SPDX-License-Identifier: Apache-2.0
package cloudflare
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/Rain-kl/Wavelet/internal/model"
"github.com/Rain-kl/Wavelet/internal/repository"
"github.com/Rain-kl/Wavelet/internal/shared/response"
"github.com/gin-gonic/gin"
)
func TestGroupFromInputTTL(t *testing.T) {
auto, manual, minimum, maximum := 1, 120, 60, 86400
tests := []struct {
name string
existing *model.CFPointingGroup
ttl *int
want int
}{
{name: "new_default_auto", want: 1},
{name: "explicit_auto", ttl: &auto, want: 1},
{name: "manual", ttl: &manual, want: 120},
{name: "minimum", ttl: &minimum, want: 60},
{name: "maximum", ttl: &maximum, want: 86400},
{name: "legacy_default", existing: &model.CFPointingGroup{}, want: 300},
{name: "preserve_manual", existing: &model.CFPointingGroup{TTL: 600}, want: 600},
{name: "preserve_auto", existing: &model.CFPointingGroup{TTL: 1}, want: 1},
{name: "manual_to_auto", existing: &model.CFPointingGroup{TTL: 600}, ttl: &auto, want: 1},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
group, err := groupFromInput(context.Background(), tt.existing, GroupInput{
Name: "custom", TargetMode: "custom", RecordType: "CNAME", RecordContent: "origin.example.com", TTL: tt.ttl,
})
if err != nil {
t.Fatalf("groupFromInput(%s) error = %v", tt.name, err)
}
if group.TTL != tt.want {
t.Errorf("groupFromInput(%s).TTL = %d, want %d", tt.name, group.TTL, tt.want)
}
})
}
}
func TestCreateGroupHandlerTTL(t *testing.T) {
tests := []struct {
name string
ttlJSON string
wantStatus int
wantTTL int
}{
{name: "omitted", wantStatus: http.StatusOK, wantTTL: 1},
{name: "auto", ttlJSON: `,"ttl":1`, wantStatus: http.StatusOK, wantTTL: 1},
{name: "manual", ttlJSON: `,"ttl":120`, wantStatus: http.StatusOK, wantTTL: 120},
{name: "zero", ttlJSON: `,"ttl":0`, wantStatus: http.StatusBadRequest},
{name: "negative", ttlJSON: `,"ttl":-1`, wantStatus: http.StatusBadRequest},
{name: "below_minimum", ttlJSON: `,"ttl":59`, wantStatus: http.StatusBadRequest},
{name: "above_maximum", ttlJSON: `,"ttl":86401`, wantStatus: http.StatusBadRequest},
{name: "fraction", ttlJSON: `,"ttl":60.5`, wantStatus: http.StatusBadRequest},
{name: "string", ttlJSON: `,"ttl":"auto"`, wantStatus: http.StatusBadRequest},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
ctx, _ := setupCloudflareLogicDB(t)
gin.SetMode(gin.TestMode)
router := gin.New()
router.Use(response.ErrorHandlerMiddleware())
router.POST("/groups", CreateGroupHandler)
body := `{"name":"custom","target_mode":"custom","record_type":"CNAME","record_content":"origin.example.com"` + tt.ttlJSON + `}`
recorder := httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPost, "/groups", strings.NewReader(body))
request.Header.Set("Content-Type", "application/json")
router.ServeHTTP(recorder, request)
if recorder.Code != tt.wantStatus {
t.Fatalf("POST /groups(%s) status = %d, body = %s, want %d", tt.name, recorder.Code, recorder.Body.String(), tt.wantStatus)
}
if tt.wantStatus != http.StatusOK {
groups, err := repository.ListCFPointingGroups(ctx)
if err != nil || len(groups) != 1 {
t.Errorf("POST /groups(%s) persisted groups = %d, error = %v, want 1 existing group", tt.name, len(groups), err)
}
return
}
var envelope struct {
Data GroupItem `json:"data"`
}
if err := json.Unmarshal(recorder.Body.Bytes(), &envelope); err != nil {
t.Fatalf("decode POST /groups(%s) error = %v", tt.name, err)
}
if envelope.Data.TTL != tt.wantTTL {
t.Errorf("POST /groups(%s).ttl = %d, want %d", tt.name, envelope.Data.TTL, tt.wantTTL)
}
stored, err := repository.GetCFPointingGroup(ctx, envelope.Data.ID)
if err != nil {
t.Fatalf("GetCFPointingGroup(%d) error = %v", envelope.Data.ID, err)
}
if stored.TTL != tt.wantTTL {
t.Errorf("persisted POST /groups(%s).ttl = %d, want %d", tt.name, stored.TTL, tt.wantTTL)
}
})
}
}
func TestUpdateGroupTTLAndReadback(t *testing.T) {
ctx, memberID := setupCloudflareLogicDB(t)
state, err := repository.GetCFPointingMemberContext(ctx, memberID)
if err != nil {
t.Fatalf("GetCFPointingMemberContext(%d) error = %v", memberID, err)
}
legacy, err := GetGroup(ctx, state.Group.ID)
if err != nil || legacy.Group.TTL != 300 {
t.Fatalf("GetGroup(legacy) = %+v, error = %v, want ttl 300", legacy, err)
}
dispatchCount := 0
restoreDispatch := SetDispatchTaskForTest(func(context.Context, string, []byte, string) (string, error) {
dispatchCount++
return "ttl-task", nil
})
t.Cleanup(restoreDispatch)
ttl := 120
input := GroupInput{Name: state.Group.Name, PrimaryNodeID: state.Group.PrimaryNodeID, Enabled: true, TTL: &ttl}
if err := repository.UpdateCFPointingMemberColumns(ctx, memberID, map[string]any{"sync_status": model.CFMemberSyncOK}); err != nil {
t.Fatalf("UpdateCFPointingMemberColumns(%d) error = %v", memberID, err)
}
updated, err := UpdateGroup(ctx, state.Group.ID, input)
if err != nil || updated.TTL != 120 {
t.Fatalf("UpdateGroup(ttl=120) = %+v, error = %v, want ttl 120", updated, err)
}
member, err := repository.GetCFPointingMemberByID(ctx, memberID)
if err != nil {
t.Fatalf("GetCFPointingMemberByID(%d) error = %v", memberID, err)
}
if member.SyncStatus != model.CFMemberSyncPending || dispatchCount != 1 {
t.Errorf("UpdateGroup(ttl=120) member status = %s, dispatches = %d, want pending and 1", member.SyncStatus, dispatchCount)
}
// 旧客户端省略新增字段时,不应将已设置的手动 TTL 重置为自动。
input.TTL = nil
if _, err := UpdateGroup(ctx, state.Group.ID, input); err != nil {
t.Fatalf("UpdateGroup(omitted ttl) error = %v", err)
}
detail, err := GetGroup(ctx, state.Group.ID)
if err != nil || detail.Group.TTL != 120 {
t.Fatalf("GetGroup(after omitted ttl) = %+v, error = %v, want ttl 120", detail, err)
}
groups, err := ListGroups(ctx)
if err != nil || len(groups) != 1 || groups[0].TTL != 120 {
t.Errorf("ListGroups() = %+v, error = %v, want one group with ttl 120", groups, err)
}
invalidTTL := 0
input.TTL = &invalidTTL
if _, err := UpdateGroup(ctx, state.Group.ID, input); err == nil {
t.Fatal("UpdateGroup(ttl=0) error = nil, want validation error")
}
stored, err := repository.GetCFPointingGroup(ctx, state.Group.ID)
if err != nil || stored.TTL != 120 || dispatchCount != 2 {
t.Errorf("UpdateGroup(invalid ttl) stored = %+v, error = %v, dispatches = %d, want ttl 120 and 2", stored, err, dispatchCount)
}
}
func TestReconcileMemberGroupTTL(t *testing.T) {
tests := []struct {
name string
targetMode string
recordType string
content string
ttl int
proxied bool
wantTTL int
}{
{name: "node_manual", targetMode: "node", recordType: "A", content: "203.0.113.10", ttl: 120, wantTTL: 120},
{name: "cname_manual", targetMode: "custom", recordType: "CNAME", content: "origin.example.com", ttl: 60, wantTTL: 60},
{name: "a_manual", targetMode: "custom", recordType: "A", content: "203.0.113.20", ttl: 600, wantTTL: 600},
{name: "aaaa_manual", targetMode: "custom", recordType: "AAAA", content: "2001:db8::1", ttl: 86400, wantTTL: 86400},
{name: "cname_auto", targetMode: "custom", recordType: "CNAME", content: "origin.example.com", ttl: 1, wantTTL: 1},
{name: "cname_legacy", targetMode: "custom", recordType: "CNAME", content: "origin.example.com", wantTTL: 300},
{name: "cname_proxied", targetMode: "custom", recordType: "CNAME", content: "origin.example.com", ttl: 120, proxied: true, wantTTL: 1},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
ctx, memberID := setupCloudflareLogicDB(t)
state, err := repository.GetCFPointingMemberContext(ctx, memberID)
if err != nil {
t.Fatalf("GetCFPointingMemberContext(%d) error = %v", memberID, err)
}
group := state.Group
group.TargetMode, group.RecordType, group.RecordContent, group.TTL = tt.targetMode, tt.recordType, tt.content, tt.ttl
if err := repository.SaveCFPointingGroup(ctx, &group); err != nil {
t.Fatalf("SaveCFPointingGroup(%s) error = %v", tt.name, err)
}
if err := repository.UpdateCFPointingMemberColumns(ctx, memberID, map[string]any{"proxied": tt.proxied}); err != nil {
t.Fatalf("UpdateCFPointingMemberColumns(%s) error = %v", tt.name, err)
}
fake := &fakeClient{}
t.Cleanup(SetClientFactoryForTest(func(string) Client { return fake }))
if err := ReconcileMember(ctx, memberID); err != nil {
t.Fatalf("ReconcileMember(%s) error = %v", tt.name, err)
}
if fake.created == nil {
t.Fatal("ReconcileMember() did not create a DNS record")
}
if got := *fake.created; got.TTL != tt.wantTTL || got.Type != tt.recordType || got.Content != tt.content || got.Proxied != tt.proxied {
t.Errorf("ReconcileMember(%s) input = %+v, want type=%s content=%s proxied=%t ttl=%d", tt.name, got, tt.recordType, tt.content, tt.proxied, tt.wantTTL)
}
})
}
}
type cachedTTLClient struct {
fakeClient
}
func (client *cachedTTLClient) GetRecord(_ context.Context, _, recordID string) (*DNSRecord, error) {
return &DNSRecord{ID: recordID, Type: "A", TTL: 300}, nil
}
func TestReconcileMemberUpdatesGroupTTL(t *testing.T) {
for _, cached := range []bool{false, true} {
t.Run(fmt.Sprintf("cached_%t", cached), func(t *testing.T) {
ctx, memberID := setupCloudflareLogicDB(t)
state, err := repository.GetCFPointingMemberContext(ctx, memberID)
if err != nil {
t.Fatalf("GetCFPointingMemberContext(%d) error = %v", memberID, err)
}
state.Group.TTL = 180
if err := repository.SaveCFPointingGroup(ctx, &state.Group); err != nil {
t.Fatalf("SaveCFPointingGroup(ttl=180) error = %v", err)
}
if err := repository.UpdateCFPointingMemberColumns(ctx, memberID, map[string]any{"proxied": false}); err != nil {
t.Fatalf("UpdateCFPointingMemberColumns(%d) error = %v", memberID, err)
}
fake := &cachedTTLClient{fakeClient: fakeClient{records: []DNSRecord{{ID: "existing", Type: "A", TTL: 300}}}}
if cached {
if err := repository.UpdateCFPointingMemberColumns(ctx, memberID, map[string]any{"cf_record_id": "existing"}); err != nil {
t.Fatalf("UpdateCFPointingMemberColumns(cached) error = %v", err)
}
}
t.Cleanup(SetClientFactoryForTest(func(string) Client { return fake }))
if err := ReconcileMember(ctx, memberID); err != nil {
t.Fatalf("ReconcileMember(cached=%t) error = %v", cached, err)
}
if fake.updated == nil || fake.updated.TTL != 180 || fake.created != nil {
t.Errorf("ReconcileMember(cached=%t) updated = %+v, created = %+v, want update ttl=180 only", cached, fake.updated, fake.created)
}
})
}
}
@@ -39,6 +39,8 @@ type GroupInput struct {
BackupNodeID *uint `json:"backup_node_id"`
DefaultProxied bool `json:"default_proxied"`
Enabled bool `json:"enabled"`
// TTL 为 1 时自动,否则为 60~86400 秒的整数;省略时创建默认自动,更新保留原值。
TTL *int `json:"ttl" example:"1"`
}
// GroupItem is the admin-facing pointing group summary.
@@ -56,6 +58,8 @@ type GroupItem struct {
MemberCount int64 `json:"member_count"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
// TTL 为 1 时自动,否则为 DNS-only 成员使用的秒数。
TTL int `json:"ttl" example:"1"`
}
// MemberCreateInput adds a ZoneDomain to a group. Nil Proxied copies the group default.
@@ -0,0 +1,86 @@
// Copyright 2026 Arctel.net
// SPDX-License-Identifier: Apache-2.0
package migrator
import (
"bytes"
"io/fs"
"path/filepath"
"testing"
"github.com/glebarez/sqlite"
"github.com/pressly/goose/v3"
"gorm.io/gorm"
)
func TestCloudflareGroupTTLMigrationsMatch(t *testing.T) {
postgresSQL, err := fs.ReadFile(migrationFS, "goose/postgres/202611080001_add_cloudflare_group_ttl.sql")
if err != nil {
t.Fatalf("read PostgreSQL TTL migration: %v", err)
}
sqliteSQL, err := fs.ReadFile(migrationFS, "goose/sqlite/202611080001_add_cloudflare_group_ttl.sql")
if err != nil {
t.Fatalf("read SQLite TTL migration: %v", err)
}
if !bytes.Equal(postgresSQL, sqliteSQL) {
t.Error("Cloudflare TTL migrations differ, want identical portable ADD/DROP COLUMN statements")
}
}
func TestCloudflareGroupTTLMigrationSQLiteUpDownUp(t *testing.T) {
conn, err := gorm.Open(sqlite.Open(filepath.Join(t.TempDir(), "cloudflare-ttl.db")), &gorm.Config{})
if err != nil {
t.Fatalf("gorm.Open(sqlite) error = %v", err)
}
sqlDB, err := conn.DB()
if err != nil {
t.Fatalf("conn.DB() error = %v", err)
}
sqlDB.SetMaxOpenConns(1)
t.Cleanup(func() {
if err := sqlDB.Close(); err != nil {
t.Errorf("sqlDB.Close() error = %v", err)
}
})
goose.SetBaseFS(migrationFS)
if err := goose.SetDialect(dialectSqlite); err != nil {
t.Fatalf("goose.SetDialect(sqlite) error = %v", err)
}
const previousVersion = int64(202610260002)
const ttlVersion = int64(202611080001)
if err := goose.UpTo(sqlDB, "goose/sqlite", previousVersion); err != nil {
t.Fatalf("goose.UpTo(previous) error = %v", err)
}
if err := conn.Exec("INSERT INTO of_cf_pointing_groups (name, primary_node_id, active_node_id) VALUES ('legacy', 0, 0)").Error; err != nil {
t.Fatalf("insert legacy group error = %v", err)
}
for cycle := range 2 {
if err := goose.UpTo(sqlDB, "goose/sqlite", ttlVersion); err != nil {
t.Fatalf("goose.UpTo(ttl), cycle %d error = %v", cycle, err)
}
var ttl int
if err := conn.Raw("SELECT ttl FROM of_cf_pointing_groups WHERE name = 'legacy'").Scan(&ttl).Error; err != nil {
t.Fatalf("read migrated ttl, cycle %d error = %v", cycle, err)
}
if ttl != 0 {
t.Errorf("migrated legacy ttl, cycle %d = %d, want compatibility sentinel 0", cycle, ttl)
}
if conn.Migrator().HasColumn("of_cf_pointing_members", "ttl") {
t.Error("TTL migration added member-level ttl, want group-level only")
}
if err := conn.Exec("UPDATE of_cf_pointing_groups SET ttl = 120 WHERE name = 'legacy'").Error; err != nil {
t.Fatalf("write manual ttl error = %v", err)
}
if err := goose.DownTo(sqlDB, "goose/sqlite", previousVersion); err != nil {
t.Fatalf("goose.DownTo(previous), cycle %d error = %v", cycle, err)
}
if conn.Migrator().HasColumn("of_cf_pointing_groups", "ttl") {
t.Errorf("goose.DownTo(previous), cycle %d left ttl column", cycle)
}
var count int64
if err := conn.Table("of_cf_pointing_groups").Where("name = ?", "legacy").Count(&count).Error; err != nil || count != 1 {
t.Fatalf("legacy groups after rollback = %d, error = %v, want 1", count, err)
}
}
}
@@ -0,0 +1,6 @@
-- +goose Up
-- 零值由业务层解释为旧分组的 300 秒 TTL;新建分组显式保存所选值。
ALTER TABLE of_cf_pointing_groups ADD COLUMN ttl INTEGER NOT NULL DEFAULT 0;
-- +goose Down
ALTER TABLE of_cf_pointing_groups DROP COLUMN ttl;
@@ -0,0 +1,6 @@
-- +goose Up
-- 零值由业务层解释为旧分组的 300 秒 TTL;新建分组显式保存所选值。
ALTER TABLE of_cf_pointing_groups ADD COLUMN ttl INTEGER NOT NULL DEFAULT 0;
-- +goose Down
ALTER TABLE of_cf_pointing_groups DROP COLUMN ttl;
+2
View File
@@ -60,6 +60,8 @@ type CFPointingGroup struct {
Enabled bool `json:"enabled" gorm:"not null;default:false"`
CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime"`
UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime"`
// TTL 为 1 时表示自动;零值兼容旧分组的 300 秒 TTL。
TTL int `json:"ttl" gorm:"not null;default:0"`
}
// TableName returns the Cloudflare pointing group table name.