biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/worker/template/internal/runtime/runner.go

@@ -0,0 +1,199 @@
+package runtime
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"time"
+)
+
+var ErrShutdownTimeout = errors.New("worker shutdown timed out")
+
+type Executor interface {
+	Execute(context.Context) (string, error)
+}
+
+type Clock interface {
+	After(time.Duration) <-chan time.Time
+}
+
+type realClock struct{}
+
+func (realClock) After(delay time.Duration) <-chan time.Time {
+	return time.After(delay)
+}
+
+type Options struct {
+	Name            string
+	Mode            string
+	TickInterval    time.Duration
+	ShutdownTimeout time.Duration
+	MaxAttempts     int
+	InitialBackoff  time.Duration
+	MaxBackoff      time.Duration
+	Executor        Executor
+	Logger          *log.Logger
+	Clock           Clock
+}
+
+type Runner struct {
+	name            string
+	mode            string
+	tickInterval    time.Duration
+	shutdownTimeout time.Duration
+	maxAttempts     int
+	initialBackoff  time.Duration
+	maxBackoff      time.Duration
+	executor        Executor
+	logger          *log.Logger
+	clock           Clock
+}
+
+func New(options Options) *Runner {
+	logger := options.Logger
+	if logger == nil {
+		logger = log.New(io.Discard, "", 0)
+	}
+	clock := options.Clock
+	if clock == nil {
+		clock = realClock{}
+	}
+	maxAttempts := options.MaxAttempts
+	if maxAttempts <= 0 {
+		maxAttempts = 1
+	}
+	initialBackoff := options.InitialBackoff
+	if initialBackoff <= 0 {
+		initialBackoff = time.Second
+	}
+	maxBackoff := options.MaxBackoff
+	if maxBackoff < initialBackoff {
+		maxBackoff = initialBackoff
+	}
+	return &Runner{
+		name:            options.Name,
+		mode:            options.Mode,
+		tickInterval:    options.TickInterval,
+		shutdownTimeout: options.ShutdownTimeout,
+		maxAttempts:     maxAttempts,
+		initialBackoff:  initialBackoff,
+		maxBackoff:      maxBackoff,
+		executor:        options.Executor,
+		logger:          logger,
+		clock:           clock,
+	}
+}
+
+func (runner *Runner) Run(ctx context.Context) error {
+	if runner.executor == nil {
+		return errors.New("executor is required")
+	}
+
+	switch runner.mode {
+	case "oneshot":
+		err := runner.executeWithRetry(ctx)
+		if ctx.Err() != nil && !errors.Is(err, ErrShutdownTimeout) {
+			return nil
+		}
+		return err
+	case "scheduled":
+		return runner.runScheduled(ctx)
+	default:
+		return errors.New("unsupported worker mode: " + runner.mode)
+	}
+}
+
+func (runner *Runner) runScheduled(ctx context.Context) error {
+	for {
+		if err := runner.executeWithRetry(ctx); err != nil {
+			if ctx.Err() != nil {
+				if errors.Is(err, ErrShutdownTimeout) {
+					return err
+				}
+				runner.logger.Printf("%s: shutdown requested", runner.name)
+				return nil
+			}
+			runner.logger.Printf("%s: execution cycle failed: %v", runner.name, err)
+		}
+
+		if err := runner.wait(ctx, runner.tickInterval); err != nil {
+			runner.logger.Printf("%s: shutdown requested", runner.name)
+			return nil
+		}
+	}
+}
+
+func (runner *Runner) executeWithRetry(ctx context.Context) error {
+	backoff := runner.initialBackoff
+	for attempt := 1; attempt <= runner.maxAttempts; attempt++ {
+		summary, err := runner.executeAttempt(ctx)
+		if err == nil {
+			runner.logger.Printf("%s: %s", runner.name, summary)
+			return nil
+		}
+		if ctx.Err() != nil || attempt == runner.maxAttempts {
+			return fmt.Errorf("execution failed after %d attempt(s): %w", attempt, err)
+		}
+
+		runner.logger.Printf(
+			"%s: attempt %d/%d failed: %v; retrying in %s",
+			runner.name,
+			attempt,
+			runner.maxAttempts,
+			err,
+			backoff,
+		)
+		if err := runner.wait(ctx, backoff); err != nil {
+			return err
+		}
+		backoff = nextBackoff(backoff, runner.maxBackoff)
+	}
+	return nil
+}
+
+func (runner *Runner) executeAttempt(ctx context.Context) (string, error) {
+	type result struct {
+		summary string
+		err     error
+	}
+
+	executionCtx, cancelExecution := context.WithCancel(context.WithoutCancel(ctx))
+	defer cancelExecution()
+	resultChannel := make(chan result, 1)
+	go func() {
+		summary, err := runner.executor.Execute(executionCtx)
+		resultChannel <- result{summary: summary, err: err}
+	}()
+
+	select {
+	case executionResult := <-resultChannel:
+		return executionResult.summary, executionResult.err
+	case <-ctx.Done():
+		cancelExecution()
+	}
+
+	select {
+	case executionResult := <-resultChannel:
+		return executionResult.summary, executionResult.err
+	case <-runner.clock.After(runner.shutdownTimeout):
+		return "", fmt.Errorf("%w after %s", ErrShutdownTimeout, runner.shutdownTimeout)
+	}
+}
+
+func (runner *Runner) wait(ctx context.Context, delay time.Duration) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-runner.clock.After(delay):
+		return nil
+	}
+}
+
+func nextBackoff(current time.Duration, maximum time.Duration) time.Duration {
+	if current >= maximum || current > maximum/2 {
+		return maximum
+	}
+	return current * 2
+}

biucingcli/template_data/worker/template/internal/runtime/runner_test.go

@@ -0,0 +1,215 @@
+package runtime
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+var errTask = errors.New("task failed")
+
+type executionResult struct {
+	summary string
+	err     error
+}
+
+type scriptedExecutor struct {
+	mu      sync.Mutex
+	results []executionResult
+	calls   int
+	execute func(context.Context) (string, error)
+}
+
+func (executor *scriptedExecutor) Execute(ctx context.Context) (string, error) {
+	if executor.execute != nil {
+		return executor.execute(ctx)
+	}
+	executor.mu.Lock()
+	defer executor.mu.Unlock()
+	executor.calls++
+	result := executor.results[executor.calls-1]
+	return result.summary, result.err
+}
+
+func (executor *scriptedExecutor) Count() int {
+	executor.mu.Lock()
+	defer executor.mu.Unlock()
+	return executor.calls
+}
+
+type clockRequest struct {
+	delay time.Duration
+	fire  chan time.Time
+}
+
+type fakeClock struct {
+	requests chan clockRequest
+}
+
+func newFakeClock() *fakeClock {
+	return &fakeClock{requests: make(chan clockRequest, 16)}
+}
+
+func (clock *fakeClock) After(delay time.Duration) <-chan time.Time {
+	fire := make(chan time.Time, 1)
+	clock.requests <- clockRequest{delay: delay, fire: fire}
+	return fire
+}
+
+func (clock *fakeClock) Next(t *testing.T) clockRequest {
+	t.Helper()
+	select {
+	case request := <-clock.requests:
+		return request
+	case <-time.After(time.Second):
+		t.Fatal("runner did not request a timer")
+		return clockRequest{}
+	}
+}
+
+func fire(request clockRequest) {
+	request.fire <- time.Time{}
+}
+
+func newTestRunner(mode string, executor Executor, clock Clock) *Runner {
+	return New(Options{
+		Name:            "demo-worker",
+		Mode:            mode,
+		TickInterval:    10 * time.Second,
+		ShutdownTimeout: 5 * time.Second,
+		MaxAttempts:     3,
+		InitialBackoff:  time.Second,
+		MaxBackoff:      2 * time.Second,
+		Executor:        executor,
+		Logger:          log.New(io.Discard, "", 0),
+		Clock:           clock,
+	})
+}
+
+func TestRunOneshotRetriesWithCappedExponentialBackoff(t *testing.T) {
+	executor := &scriptedExecutor{results: []executionResult{
+		{err: errTask}, {err: errTask}, {summary: "heartbeat completed"},
+	}}
+	clock := newFakeClock()
+	done := make(chan error, 1)
+	go func() { done <- newTestRunner("oneshot", executor, clock).Run(context.Background()) }()
+
+	firstBackoff := clock.Next(t)
+	if firstBackoff.delay != time.Second {
+		t.Fatalf("expected first backoff %s, got %s", time.Second, firstBackoff.delay)
+	}
+	fire(firstBackoff)
+	secondBackoff := clock.Next(t)
+	if secondBackoff.delay != 2*time.Second {
+		t.Fatalf("expected capped second backoff %s, got %s", 2*time.Second, secondBackoff.delay)
+	}
+	fire(secondBackoff)
+
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+	if executor.Count() != 3 {
+		t.Fatalf("expected three attempts, got %d", executor.Count())
+	}
+}
+
+func TestRunOneshotReturnsFinalErrorAfterRetryExhaustion(t *testing.T) {
+	executor := &scriptedExecutor{results: []executionResult{{err: errTask}, {err: errTask}, {err: errTask}}}
+	clock := newFakeClock()
+	done := make(chan error, 1)
+	go func() { done <- newTestRunner("oneshot", executor, clock).Run(context.Background()) }()
+
+	fire(clock.Next(t))
+	fire(clock.Next(t))
+	err := <-done
+	if !errors.Is(err, errTask) || !strings.Contains(err.Error(), "after 3 attempt(s)") {
+		t.Fatalf("expected exhausted retry error, got %v", err)
+	}
+}
+
+func TestRunScheduledContinuesAfterRetryExhaustion(t *testing.T) {
+	executor := &scriptedExecutor{results: []executionResult{
+		{err: errTask}, {err: errTask}, {err: errTask}, {summary: "next cycle completed"},
+	}}
+	clock := newFakeClock()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- newTestRunner("scheduled", executor, clock).Run(ctx) }()
+
+	fire(clock.Next(t))
+	fire(clock.Next(t))
+	scheduleDelay := clock.Next(t)
+	if scheduleDelay.delay != 10*time.Second {
+		t.Fatalf("expected schedule delay %s, got %s", 10*time.Second, scheduleDelay.delay)
+	}
+	fire(scheduleDelay)
+	nextSchedule := clock.Next(t)
+	if nextSchedule.delay != 10*time.Second {
+		t.Fatalf("expected next schedule delay %s, got %s", 10*time.Second, nextSchedule.delay)
+	}
+	cancel()
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+	if executor.Count() != 4 {
+		t.Fatalf("expected four attempts across two cycles, got %d", executor.Count())
+	}
+}
+
+func TestCancellationInterruptsRetryBackoff(t *testing.T) {
+	executor := &scriptedExecutor{results: []executionResult{{err: errTask}}}
+	clock := newFakeClock()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- newTestRunner("oneshot", executor, clock).Run(ctx) }()
+
+	request := clock.Next(t)
+	if request.delay != time.Second {
+		t.Fatalf("expected retry backoff %s, got %s", time.Second, request.delay)
+	}
+	cancel()
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+	if executor.Count() != 1 {
+		t.Fatalf("expected cancellation to prevent another attempt, got %d", executor.Count())
+	}
+}
+
+func TestShutdownTimeoutIsDeterministic(t *testing.T) {
+	releaseExecutor := make(chan struct{})
+	defer close(releaseExecutor)
+	executor := &scriptedExecutor{execute: func(ctx context.Context) (string, error) {
+		<-ctx.Done()
+		<-releaseExecutor
+		return "", ctx.Err()
+	}}
+	clock := newFakeClock()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- newTestRunner("oneshot", executor, clock).Run(ctx) }()
+
+	cancel()
+	shutdownTimer := clock.Next(t)
+	if shutdownTimer.delay != 5*time.Second {
+		t.Fatalf("expected shutdown timeout %s, got %s", 5*time.Second, shutdownTimer.delay)
+	}
+	fire(shutdownTimer)
+	if err := <-done; !errors.Is(err, ErrShutdownTimeout) {
+		t.Fatalf("expected shutdown timeout, got %v", err)
+	}
+}
+
+func TestNextBackoffCapsWithoutOverflow(t *testing.T) {
+	if actual := nextBackoff(time.Second, 2*time.Second); actual != 2*time.Second {
+		t.Fatalf("expected doubled backoff, got %s", actual)
+	}
+	if actual := nextBackoff(2*time.Second, 2*time.Second); actual != 2*time.Second {
+		t.Fatalf("expected capped backoff, got %s", actual)
+	}
+}

biucingcli/template_data/worker/template/internal/task/heartbeat.go

@@ -0,0 +1,19 @@
+package task
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+type HeartbeatTask struct {
+	workerName string
+}
+
+func NewHeartbeatTask(workerName string) *HeartbeatTask {
+	return &HeartbeatTask{workerName: workerName}
+}
+
+func (task *HeartbeatTask) Execute(context.Context) (string, error) {
+	return fmt.Sprintf("%s heartbeat completed at %s", task.workerName, time.Now().UTC().Format(time.RFC3339)), nil
+}

biucingcli/template_data/worker/template/scripts/bootstrap

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -eu
+
+mkdir -p .cache/go-build bin
+go mod tidy
+go test ./...

biucingcli/template_data/worker/template/scripts/doctor

@@ -0,0 +1,41 @@
+#!/usr/bin/env sh
+set -eu
+
+issues=0
+
+echo "Worker environment doctor"
+
+if command -v go >/dev/null 2>&1; then
+  echo "go is available"
+else
+  echo "go is not installed or not on PATH."
+  issues=$((issues + 1))
+fi
+
+if command -v docker >/dev/null 2>&1; then
+  echo "docker is available"
+else
+  echo "docker is not installed or not on PATH."
+  issues=$((issues + 1))
+fi
+
+if [ -f configs/config.json ]; then
+  echo "configs/config.json is present"
+else
+  echo "configs/config.json is missing"
+  issues=$((issues + 1))
+fi
+
+if [ -f go.mod ]; then
+  echo "go.mod is present"
+else
+  echo "go.mod is missing"
+  issues=$((issues + 1))
+fi
+
+if [ "$issues" -gt 0 ]; then
+  echo "Doctor found $issues issue(s)."
+  exit 1
+fi
+
+echo "Environment looks ready."

biucingcli/template_data/worker/template/tests/worker_test.go

@@ -0,0 +1,44 @@
+package tests
+
+import (
+	"context"
+	"io"
+	"log"
+	"testing"
+	"time"
+
+	"{{MODULE_NAME}}/internal/config"
+	"{{MODULE_NAME}}/internal/runtime"
+	"{{MODULE_NAME}}/internal/task"
+)
+
+func TestWorkerConfigDefaults(t *testing.T) {
+	t.Setenv("CONFIG_FILE", "../configs/config.json")
+
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if cfg.Worker.Name != "{{WORKER_NAME}}" {
+		t.Fatalf("expected worker name %q, got %q", "{{WORKER_NAME}}", cfg.Worker.Name)
+	}
+	if cfg.Worker.RunMode != "{{RUN_MODE}}" {
+		t.Fatalf("expected run mode %q, got %q", "{{RUN_MODE}}", cfg.Worker.RunMode)
+	}
+}
+
+func TestOneshotRunnerUsesHeartbeatTask(t *testing.T) {
+	runner := runtime.New(runtime.Options{
+		Name:            "{{WORKER_NAME}}",
+		Mode:            "oneshot",
+		TickInterval:    10 * time.Millisecond,
+		ShutdownTimeout: time.Second,
+		Executor:        task.NewHeartbeatTask("{{WORKER_NAME}}"),
+		Logger:          log.New(io.Discard, "", 0),
+	})
+
+	if err := runner.Run(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}

biucingcli/template_data/worker/template.json

@@ -0,0 +1,100 @@
+{
+  "name": "worker",
+  "description": "Go background worker starter with scheduled and oneshot execution modes",
+  "category": "backend",
+  "stack": ["Go", "Docker"],
+  "tags": ["worker", "docker", "go", "async"],
+  "platforms": ["linux", "container"],
+  "maturity": {
+    "level": "validated",
+    "summary": "Dockerized worker starter with explicit retry semantics, bounded shutdown, and deterministic generated-project tests."
+  },
+  "validation": {
+    "status": "generated-project-verified",
+    "verification_tier": "generated-project",
+    "evidence": [
+      "python unittest template rendering coverage",
+      "deterministic injected-clock retry and scheduling tests",
+      "real generated project go test validation"
+    ]
+  },
+  "operating_assumptions": [
+    "The starter is optimized for background execution rather than a public HTTP API surface.",
+    "Generated projects are expected to keep config, verification, and container packaging repo-local."
+  ],
+  "workflow_labels": ["bootstrap", "dev", "verify", "build", "runtime"],
+  "commands": {
+    "bootstrap": "make bootstrap",
+    "doctor": "make doctor",
+    "lint": "make lint",
+    "test": "make test",
+    "verify": "make verify",
+    "build": "make build",
+    "clean": "make clean",
+    "help": "make help"
+  },
+  "worktree": {
+    "support_level": "worktree-ready",
+    "isolation_dimensions": [
+      "runtime-names",
+      "caches",
+      "generated-output",
+      "cleanup",
+      "diagnostics"
+    ],
+    "diagnostics": [
+      "make worktree-info",
+      "make worktree-doctor"
+    ],
+    "cleanup": [
+      "make clean-worktree"
+    ]
+  },
+  "variables": [
+    {
+      "name": "project_name",
+      "required": true,
+      "validator": "project-name"
+    },
+    {
+      "name": "module_name",
+      "required": true,
+      "prompt": "Go module name: ",
+      "validator": "go-module"
+    },
+    {
+      "name": "worker_name",
+      "required": false,
+      "default_from": "project_name",
+      "validator": "slug"
+    },
+    {
+      "name": "run_mode",
+      "required": false,
+      "default": "scheduled",
+      "validator": "choice",
+      "choices": ["scheduled", "oneshot"]
+    },
+    {
+      "name": "tick_interval_seconds",
+      "required": false,
+      "default": "30",
+      "validator": "positive-integer",
+      "maximum": 86400
+    },
+    {
+      "name": "shutdown_timeout_seconds",
+      "required": false,
+      "default": "10",
+      "validator": "positive-integer",
+      "maximum": 3600
+    }
+  ],
+  "next_steps": [
+    "make bootstrap",
+    "make dev",
+    "make verify",
+    "make docker-build",
+    "make docker-run"
+  ]
+}