Files
dobotai-platform/internal/questiontable/dispatcher.go

234 lines
7.3 KiB
Go

package questiontable
import (
"context"
"errors"
"fmt"
"reflect"
"strings"
"time"
)
// FailureCodeRemoteInsertFailed is the stable public failure code used when
// InsertRecord returns an error. The raw error is never persisted or returned.
const FailureCodeRemoteInsertFailed = "remote_question_table_insert_failed"
// PendingExport is a row waiting to be exported to the remote question table.
type PendingExport struct {
ExportID string
Row Row
Attempts int
}
// ExportRepository is the persistence contract for the background dispatcher.
type ExportRepository interface {
// Claim returns up to limit pending exports whose attempt count is below
// maxAttempts and whose last claim time is before staleBefore.
Claim(ctx context.Context, limit int, maxAttempts int, staleBefore time.Time) ([]PendingExport, error)
// MarkExported records the location (Notable record ID) for a successfully exported row.
MarkExported(ctx context.Context, exportID, location string) error
// MarkFailed records a failure for the given exportID with a stable failure code.
MarkFailed(ctx context.Context, exportID, failureCode string) error
}
// RecordInserter is the contract for inserting a row to the remote Notable base.
// *Client.InsertRecord satisfies this interface.
type RecordInserter interface {
InsertRecord(ctx context.Context, row Row) (string, error)
}
// AnswerRewriter optionally transforms the answer before it is written to the
// question table, applying the same outbound conversion used for DingTalk
// delivery (resource images to stable HTTPS, document links, anchor cleanup).
// When nil or when Rewrite returns an error, the original answer is written so
// the record is never lost.
type AnswerRewriter interface {
Rewrite(ctx context.Context, content string) (string, error)
}
// DispatcherStats holds the outcome counters for a single RunOnce invocation.
type DispatcherStats struct {
Claimed int
Exported int
Failed int
}
// DispatcherOptions holds optional configuration for the Dispatcher.
type DispatcherOptions struct {
Batch int
MaxAttempts int
ClaimLease time.Duration
SendTimeout time.Duration
Rewriter AnswerRewriter
}
// Dispatcher runs the background dispatch loop that claims pending exports
// and inserts them to the remote question table.
type Dispatcher struct {
repo ExportRepository
inserter RecordInserter
rewriter AnswerRewriter
batch int
maxAttempts int
claimLease time.Duration
sendTimeout time.Duration
}
// isNil reports whether x is nil. It accepts any value and only calls
// IsNil when the underlying kind is nil-able. Value types (structs, ints,
// strings, etc.) are never nil and return false without panicking.
func isNil(x interface{}) bool {
if x == nil {
return true
}
v := reflect.ValueOf(x)
switch v.Kind() {
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice:
return v.IsNil()
default:
return false
}
}
// NewDispatcher creates a validated Dispatcher. It returns an error when repo
// or inserter is nil (including typed nil), or when any option value is out of
// bounds. Defaults: batch=10, maxAttempts=5, claimLease=5m, sendTimeout=10s.
func NewDispatcher(repo ExportRepository, inserter RecordInserter, opts *DispatcherOptions) (*Dispatcher, error) {
if isNil(repo) {
return nil, errors.New("questiontable dispatcher: repo is nil")
}
if isNil(inserter) {
return nil, errors.New("questiontable dispatcher: inserter is nil")
}
batch := 10
maxAttempts := 5
claimLease := 5 * time.Minute
sendTimeout := 10 * time.Second
var rewriter AnswerRewriter
if opts != nil {
rewriter = opts.Rewriter
if opts.Batch < 0 {
return nil, fmt.Errorf("questiontable dispatcher: batch must be >= 0, got %d", opts.Batch)
}
if opts.Batch > 0 {
batch = opts.Batch
}
if opts.MaxAttempts < 0 {
return nil, fmt.Errorf("questiontable dispatcher: maxAttempts must be >= 0, got %d", opts.MaxAttempts)
}
if opts.MaxAttempts > 0 {
maxAttempts = opts.MaxAttempts
}
if opts.ClaimLease < 0 {
return nil, fmt.Errorf("questiontable dispatcher: claimLease must be >= 0, got %v", opts.ClaimLease)
}
if opts.ClaimLease > 0 {
claimLease = opts.ClaimLease
}
if opts.SendTimeout < 0 {
return nil, fmt.Errorf("questiontable dispatcher: sendTimeout must be >= 0, got %v", opts.SendTimeout)
}
if opts.SendTimeout > 0 {
sendTimeout = opts.SendTimeout
}
}
return &Dispatcher{
repo: repo,
inserter: inserter,
rewriter: rewriter,
batch: batch,
maxAttempts: maxAttempts,
claimLease: claimLease,
sendTimeout: sendTimeout,
}, nil
}
// RunOnce claims pending exports and dispatches them to the remote table.
// It returns stats and any error that prevented the entire operation.
// Individual row failures are tracked in stats.Failed and do not cause
// RunOnce to return an error.
func (d *Dispatcher) RunOnce(ctx context.Context) (DispatcherStats, error) {
var stats DispatcherStats
// Parent context precheck.
if err := ctx.Err(); err != nil {
return stats, fmt.Errorf("questiontable dispatcher: context invalid: %w", err)
}
staleBefore := time.Now().Add(-d.claimLease)
items, err := d.repo.Claim(ctx, d.batch, d.maxAttempts, staleBefore)
if err != nil {
// Repository errors are not trusted; return stable stage-only error.
return stats, errors.New("questiontable dispatcher: claim failed")
}
stats.Claimed = len(items)
for _, item := range items {
// Check parent context before each item.
if err := ctx.Err(); err != nil {
return stats, fmt.Errorf("questiontable dispatcher: context cancelled during dispatch: %w", err)
}
row := item.Row
if err := d.rewriteAnswer(ctx, &row); err != nil {
// Rewriting is best-effort: the original answer is written so the
// question-table record is never lost. Only the row is skipped when
// the parent context is cancelled.
if ctx.Err() != nil {
return stats, fmt.Errorf("questiontable dispatcher: context cancelled during rewrite: %w", ctx.Err())
}
}
sendCtx, cancel := context.WithTimeout(ctx, d.sendTimeout)
recordID, insertErr := d.inserter.InsertRecord(sendCtx, row)
cancel()
if insertErr != nil {
// Mark failed with stable code only; raw error not persisted.
if markErr := d.repo.MarkFailed(ctx, item.ExportID, FailureCodeRemoteInsertFailed); markErr != nil {
// Repository errors are not trusted; return stable stage-only error.
return stats, errors.New("questiontable dispatcher: mark failed failed")
}
stats.Failed++
continue
}
// Mark exported with returned Notable record ID.
if markErr := d.repo.MarkExported(ctx, item.ExportID, recordID); markErr != nil {
// Repository errors are not trusted; return stable stage-only error.
return stats, errors.New("questiontable dispatcher: mark exported failed")
}
stats.Exported++
}
return stats, nil
}
// rewriteAnswer transforms the outbound answer when an AnswerRewriter is
// configured. A nil rewriter or a rewriter error leaves the original answer
// intact; the row is never skipped for a rewriter error.
func (d *Dispatcher) rewriteAnswer(ctx context.Context, row *Row) error {
if d.rewriter == nil {
return nil
}
rewritten, err := d.rewriter.Rewrite(ctx, row.Answer)
if err != nil {
return err
}
if strings.TrimSpace(rewritten) != "" {
row.Answer = rewritten
}
return nil
}