From ee7fc0785e74556f5bac1363ac02a9208230dee6 Mon Sep 17 00:00:00 2001
From: "F." <fc@hyperd.io>
Date: Thu, 22 Jan 2026 20:24:41 +0100
Subject: [PATCH] docs(scheduler): expand PRD with Scheduler Extension and add
 sectools dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update PRD title to “Retrier Hardening + Scheduler Extension”.
- Document new lightweight scheduler for recurring HTTP requests:
  - Interval scheduling with StartAt/EndAt/MaxRuns and concurrency-safe execution.
  - Reuse existing retrier for retryable codes/errors; stop on success or non-retryable statuses.
  - Optional callback URL to post execution results (bounded response body; skipped when empty).
  - Default URL validation via sectools (HTTPS only, no userinfo/private/localhost), with override/disable knob.
- Clarify scope: no persistent storage, cron syntax, or non-HTTP protocols.
- Add detailed Requirements, Acceptance Criteria, Test Plan, Decisions, and Status sections.
- Update Dependencies to include github.com/hyp3rd/sectools.

Refs: PRD.md
---
 PRD.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/PRD.md b/PRD.md
index b5a3f82..345bc5d 100644
--- a/PRD.md
+++ b/PRD.md
@@ -1,4 +1,4 @@
-# PRD: go-again Retrier Hardening
+# PRD: go-again Retrier Hardening + Scheduler Extension
 
 ## Context
 
@@ -97,9 +97,68 @@
 
 ## Dependencies
 
-- Go toolchain (module `go.mod`), `github.com/hyp3rd/ewrap`.
+- Go toolchain (module `go.mod`), `github.com/hyp3rd/ewrap`, `github.com/hyp3rd/sectools`.
 
 ## Rollout
 
 - Cut a patch release after tests pass.
 - Add brief release notes covering retry correctness and documentation fixes.
+
+## Scheduler Extension
+
+### Context (Scheduler Extension)
+
+`go-again` now includes a lightweight scheduler for recurring HTTP requests with retry support and optional callbacks.
+
+### Goals (Scheduler Extension)
+
+- Schedule HTTP requests on an interval with optional `StartAt`, `EndAt`, and `MaxRuns`.
+- Post execution results to an optional callback URL with a bounded response body.
+- Reuse the retrier for retryable status codes and error classes.
+- Validate request and callback URLs by default, with the ability to customize or disable validation.
+- Support custom HTTP clients, concurrency limits, and logging hooks.
+
+### Non-Goals (Scheduler Extension)
+
+- Persistent schedule storage or distributed coordination.
+- Cron expression support.
+- Non-HTTP protocols or gRPC endpoints.
+
+### Requirements (Scheduler Extension)
+
+#### Functional (Scheduler Extension)
+
+- Support `GET`, `POST`, `PUT` for requests and callbacks.
+- Validate URLs with sectools defaults (HTTPS only, no userinfo, no private/localhost).
+- Provide `WithURLValidator` to override or disable validation.
+- Allow retries via `RetryPolicy` (`Retrier`, `TemporaryErrors`, `RetryStatusCodes`).
+- Skip callbacks when `Callback.URL` is empty.
+
+#### Non-Functional (Scheduler Extension)
+
+- Concurrency-safe scheduling and execution.
+- Avoid global mutable state; keep overhead minimal.
+
+### Acceptance Criteria (Scheduler Extension)
+
+- Schedules respect `StartAt`, `EndAt`, and `MaxRuns`.
+- Retry stops on success; non-retryable statuses stop immediately.
+- Callback payload includes attempts, status, error, and bounded response body.
+- URL validation is enforced by default and can be disabled.
+
+### Test Plan (Scheduler Extension)
+
+- Retry and callback flow is covered with TLS endpoints.
+- Validation rejects non-HTTPS URLs; disabling validation allows HTTP.
+- `EndAt` in the past skips execution.
+- `Remove` cancels pending jobs before execution.
+- Non-retryable status returns after one attempt.
+
+### Decisions (Scheduler Extension)
+
+- Use sectools URL validation by default.
+- Allow callers to provide a custom validator or disable validation with `nil`.
+
+### Status (Scheduler Extension)
+
+- Tests and race checks are reported green with no behavioral changes.