diff --git a/plugins/notices/eol/eol.go b/plugins/notices/eol/eol.go index b4cc78b..4c9d852 100644 --- a/plugins/notices/eol/eol.go +++ b/plugins/notices/eol/eol.go @@ -10,14 +10,15 @@ // says what the plugin actually saw. // // Salesforce's docs site is the one difference from the other notices -// readers: it answers 403 to a plain GET (checked 2026-11-20, including with -// a browser User-Agent), so a direct read of the live page fails every time. The -// Wayback Machine's own save-page-now request succeeds against it anyway, -// and its capture parses to the same findings the live page would (checked -// the same day), so the kind falls back to a fresh snapshot on a 401 or 403 -// (ArchiveWhenBlocked), +// readers: it blocks a plain GET, with 403 (checked 2026-11-20, including +// with a browser User-Agent) or, from its CDN (AkamaiNetStorage), 503 +// (checked 2026-11-21), so a direct read of the live page fails every time. +// The Wayback Machine's own crawler reads it anyway (its capture of +// 2026-11-20 parses to the same findings the live page would), so the kind +// falls back to a fresh snapshot on those statuses (ArchiveWhenBlocked), // used directly as both the content and its own citation, kit.Cite's // double-check skipped: there is no separate live read left to agree with. +// A snapshot that can't be taken, or holds no table, fails the run. // // Unlike retirements (one named model per row) and feed (an RSS or Atom // entry), a row here names a whole range of version numbers and no @@ -191,10 +192,10 @@ func (pg Page) Find(page []byte) (kit.Notices, error) { return Read(fs), err } -// ArchiveWhenBlocked is on: Salesforce's docs site answers 403 to a plain -// GET, so the kind reads a fresh Wayback Machine snapshot instead (see the -// package comment). -func (Page) ArchiveWhenBlocked() bool { return true } +// ArchiveWhenBlocked is the statuses Salesforce's docs site blocks a plain +// GET with (401 and 403; 503 from its CDN), so the kind reads a fresh +// Wayback Machine snapshot instead (see the package comment). +func (Page) ArchiveWhenBlocked() []int { return []int{401, 403, 503} } // Events are an event per version number a row retires or deprecates, // citing citeURL, with previous as previous_version (each is an diff --git a/plugins/notices/eol_test.go b/plugins/notices/eol_test.go index 53558e4..f0135a4 100644 --- a/plugins/notices/eol_test.go +++ b/plugins/notices/eol_test.go @@ -2,11 +2,13 @@ package notices import ( "context" + "errors" "fmt" "testing" "time" "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/kit" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" @@ -60,12 +62,12 @@ func TestDropsAStillSupportedBand(t *testing.T) { } } -// eol.Salesforce's docs site answers 403 to a plain GET; the live page is never -// reachable through env.Get. Read must fall back to the Wayback Machine's own -// fetch and use its snapshot directly, not fail outright. 401 falls back the -// same way. +// eol.Salesforce's docs site answers 403 to a plain GET, or 503 from its CDN; +// the live page is never reachable through env.Get. Read must fall back to +// the Wayback Machine's own fetch and use its snapshot directly, not fail +// outright. 401 falls back the same way. func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { - for _, code := range []int{401, 403} { + for _, code := range []int{401, 403, 503} { t.Run(fmt.Sprint(code), func(t *testing.T) { saved := kittest.Pages{eol.Salesforce.URL: "eol/testdata/salesforce-api-rest-eol-2026-10-31.html"} archive := &kittest.Archive{T: t, Pages: saved} @@ -97,10 +99,10 @@ func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { } // A real failure (not the provider blocking a plain fetch) must stay a -// failure: falling back to the archive for a timeout or a 5xx would hide it -// as a real page. +// failure: falling back to the archive for a timeout, a moved page or a 5xx +// the reader doesn't name would hide it as a real page. func TestDoesNotFallBackOnATransientError(t *testing.T) { - for _, code := range []int{404, 429, 503} { + for _, code := range []int{404, 429, 500, 502} { t.Run(fmt.Sprint(code), func(t *testing.T) { env := plugin.Env{ Get: func(context.Context, string) ([]byte, error) { @@ -117,3 +119,37 @@ func TestDoesNotFallBackOnATransientError(t *testing.T) { }) } } + +// A blocked page that the archive can't capture, or whose capture holds no +// table (a block page saved in its place), fails the read: the run records +// an error, never "nothing changed" and never a skip. +func TestABlockedPageTheArchiveCantReadIsAFailedRun(t *testing.T) { + blocked := plugin.Env{ + Get: func(context.Context, string) ([]byte, error) { + return nil, &fetch.StatusError{URL: eol.Salesforce.URL, StatusCode: 403} + }, + Now: func() time.Time { return kittest.Clock }, + } + last := plugin.Snapshot{Version: plugin.Version{ID: "2026-11-01T00:00:00Z"}, Content: []byte("
"), CompareHash: "x"} + for name, archive := range map[string]kit.Archiver{ + "no snapshot": failingArchive{}, + "a block page": blockPage{}, + } { + _, err := Plugin{Page: eol.Salesforce, Archiver: archive}.Read(context.Background(), blocked, last) + if err == nil || errors.Is(err, plugin.ErrNothingToRead) { + t.Errorf("%s: %v, want a failure that isn't plugin.ErrNothingToRead", name, err) + } + } +} + +type failingArchive struct{} + +func (failingArchive) Snapshot(context.Context, string) (string, []byte, error) { + return "", nil, errors.New("the Wayback Machine didn't snapshot it") +} + +type blockPage struct{} + +func (blockPage) Snapshot(_ context.Context, u string) (string, []byte, error) { + return "https://web.archive.org/web/20261121000000/" + u, []byte("Access Denied"), nil +} diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go index dfe3358..64248a7 100644 --- a/plugins/notices/notices.go +++ b/plugins/notices/notices.go @@ -11,8 +11,15 @@ // // Two options a reader turns on with a method: ShapeGuard (a read with fewer // than 90% of the last one's notices is an error: the page changed shape), -// and ArchiveWhenBlocked (a live page that answers 401 or 403 is read from a -// fresh Wayback Machine snapshot instead). +// and ArchiveWhenBlocked (a live page that answers one of the statuses its +// provider blocks plain fetches with is read from a fresh Wayback Machine +// snapshot instead). +// +// A living page that can't be read is a failed run, never "nothing +// changed": a page with no notices to read (plugin.ErrNothingToRead from its +// reader) is the page changing shape or a block page served in its place, +// so Read returns it as a plain error, which errors.Is doesn't take for +// nothing to read. package notices import ( @@ -20,6 +27,7 @@ import ( "errors" "fmt" "log" + "slices" "time" "github.com/patch-it-dev/patch-it-plugins/core/event" @@ -111,8 +119,9 @@ type Page interface { type shapeGuarded interface{ ShapeGuard() bool } // archivedWhenBlocked is a Page read from a fresh Wayback Machine snapshot -// when the live page refuses a plain fetch. -type archivedWhenBlocked interface{ ArchiveWhenBlocked() bool } +// when the live page refuses a plain fetch: ArchiveWhenBlocked is the HTTP +// statuses its provider blocks one with. +type archivedWhenBlocked interface{ ArchiveWhenBlocked() []int } // Plugin reads one page. type Plugin struct { @@ -141,6 +150,11 @@ func (p Plugin) Read(ctx context.Context, env plugin.Env, last plugin.Snapshot) return last, nil } want, err := pg.Find(live) + if errors.Is(err, plugin.ErrNothingToRead) { + // Not a skip: the page this source reads holds no notices, so it + // changed shape or something else was served in its place. + return plugin.Snapshot{}, fmt.Errorf("reading %s: the page has no notices to read, it may be blocked or have changed shape: %v", url, err) + } if err != nil { return plugin.Snapshot{}, fmt.Errorf("reading %s: %w", url, err) } @@ -166,19 +180,21 @@ func (p Plugin) Read(ctx context.Context, env plugin.Env, last plugin.Snapshot) // fetch reads the live page. When the page's reader asks for it // (ArchiveWhenBlocked) and the provider's own site blocks a plain fetch with -// 401 or 403 (Salesforce's docs site, every time, checked 2026-11-20; -// confirmed the same day that a real Wayback Machine save-page-now capture -// of that page parses to the same findings as the live page would), it -// falls back to a fresh Wayback Machine snapshot, taken right now by the -// archive's own crawler rather than patch-it's, and returns that content -// with its own permanent URL in archivedURL: it needs no further citation -// step, having come from the archive already. +// one of the statuses the reader names (Salesforce's docs site: 403 on +// 2026-11-20, 503 from its CDN on 2026-11-21, after fetch's own retries; +// confirmed on 2026-11-20 that a real Wayback Machine capture of that page +// parses to the same findings as the live page would), it falls back to a +// fresh Wayback Machine snapshot, taken right now by the archive's own +// crawler rather than patch-it's, and returns that content with its own +// permanent URL in archivedURL: it needs no further citation step, having +// come from the archive already. // -// Only 401 and 403 fall back. A 404 or 410 means the page moved, not that -// it's blocked: asking the archive to snapshot a page that's gone would -// waste the call and hide the real cause behind the archive's own error. -// A 429 or a 5xx is returned as is: retrying it against the archive would -// hide a transient failure as a real page, not fix one. +// Any other status is returned as is. A 404 or 410 means the page moved, +// not that it's blocked: asking the archive to snapshot a page that's gone +// would waste the call and hide the real cause behind the archive's own +// error. A 429, or a 5xx the reader doesn't name, is a transient failure: +// retrying it against the archive would hide it as a real page. Either way +// the run fails, and so does a fallback whose snapshot can't be taken. func (p Plugin) fetch(ctx context.Context, env plugin.Env, pageURL string) (body []byte, archivedURL string, err error) { body, err = env.Get(ctx, pageURL) if err == nil { @@ -186,7 +202,7 @@ func (p Plugin) fetch(ctx context.Context, env plugin.Env, pageURL string) (body } b, ok := p.Page.(archivedWhenBlocked) var se *fetch.StatusError - if !ok || !b.ArchiveWhenBlocked() || !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) { + if !ok || !errors.As(err, &se) || !slices.Contains(b.ArchiveWhenBlocked(), se.StatusCode) { return nil, "", err } archivedURL, body, archErr := p.Archiver.Snapshot(ctx, pageURL) diff --git a/providers/salesforce.md b/providers/salesforce.md index 2edf69d..7103ea0 100644 --- a/providers/salesforce.md +++ b/providers/salesforce.md @@ -8,12 +8,13 @@ Kind: `notices` (`plugins/notices`), with the end-of-life reader (`plugins/notic ## Why this source -- **Source:** [API End-of-Life Policy](https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html), Salesforce's own table of REST API version ranges and their support status. Checked 2026-11-20: a plain GET of the live page gets a 403 every time, including with a browser `User-Agent`, so `env.Get` always fails here. The Wayback Machine's own save-page-now request succeeds against the same URL anyway (checked the same day), so this plugin falls back to a fresh snapshot when the direct read is blocked, and reads and cites that snapshot directly: unlike `retirements` and `feed`, which read the live page first and only snapshot it afterward to cite, there's no live read here to cite alongside. +- **Source:** [API End-of-Life Policy](https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html), Salesforce's own table of REST API version ranges and their support status. Checked 2026-11-20: a plain GET of the live page gets a 403 every time, including with a browser `User-Agent`; on 2026-11-21 its CDN (`server: AkamaiNetStorage`) answered 503 instead, after the fetch layer's retries. So `env.Get` always fails here. The Wayback Machine's own crawler reads the same URL anyway (its capture of 2026-11-20 parses to the same findings), so this plugin falls back to a fresh snapshot when the direct read is blocked (401, 403, or 503), and reads and cites that snapshot directly: unlike `retirements` and `feed`, which read the live page first and only snapshot it afterward to cite, there's no live read here to cite alongside. **A read that can't be made is a failed run, never "nothing changed":** any other status (404, 429, 500…), a snapshot the archive can't take, or a snapshot with no table in it (a block page saved in its place) fails the read, and patch-it's hosted ingestion service records the error. - **Why this one:** it's the only place Salesforce states, in one page, which whole version ranges still work, which are scheduled to stop, and which already have. Salesforce's own policy text above the table: "Salesforce is committed to supporting each API version for a minimum of 3 years from the date of first release... Salesforce notifies customers who use an API version scheduled for deprecation at least 1 year before support for the version ends." - **Alternatives considered:** - **A changelog or RSS/Atom feed.** None found. Salesforce Help's release notes (HTML and PDF, three times a year: Spring, Summer, Winter) cover new features and, inconsistently, "Critical Updates" with their own auto-activation dates, but as prose spread across hundreds of pages per release, not a page or feed keyed by what changed in the API. No official feed of any of this exists. - **An OpenAPI spec.** Salesforce publishes no stable, versioned one. There's a beta, on-demand generator (`POST .../async/specifications/oas3`) for the sObjects REST API only, explicitly "subject to change... Don't build production integrations based on this," generated live per org and not pinned to a release, so there's nothing to diff between two points in time. - **Official Python and JS/TS SDKs for the REST API.** Checked 2026-11-20: Salesforce publishes none. `simple-salesforce` (PyPI) and `jsforce` (npm) are the community-maintained libraries almost everyone actually uses, but they're not Salesforce's own, so a breaking change in either is about the library, not the API; left for a future, separate client-library plugin if either becomes worth watching on its own. Salesforce does maintain its own SDKs for other surfaces (the `sf` CLI, Lightning Web Components), just not a general REST/SOAP API client. + - **The docs site's JSON content API** (`https://developer.salesforce.com/docs/get_document_content/api_rest/api_rest_eol.htm/en-us/`, the older "atlas" REST API Developer Guide; `get_document/atlas.en-us.api_rest.meta` names the newest doc version). It answers a plain GET (checked 2026-11-21), but it lags the live page: its newest version, 262.0 (Summer '26), lists versions 31.0 through 66.0 as supported and has no row for the 31.0–40.0 deprecation the live page announces, so it would miss exactly what this source is for. - **The retirement-detail sub-pages** the main table links to (e.g. "Salesforce Platform API Versions 31.0 through 40.0 Retirement"), each its own Salesforce Help article. The main page already states the same range, status and season; reading only it keeps one source of truth and one snapshot per run. - **Quote:** "As of Summer ’25, these versions are retired and unavailable." (versions 21.0 through 30.0, a real, already-happened retirement)