Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/plugins.json
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,16 @@
"status": "live",
"provider_page": "providers/redis.md"
},
{
"id": "salesforce",
"provider": "Salesforce",
"layer": "api",
"watches": "REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page",
"format": "eol",
"source_url": "https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html",
"status": "live",
"provider_page": "providers/salesforce.md"
},
{
"id": "sentry",
"provider": "Sentry",
Expand Down
3 changes: 2 additions & 1 deletion docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe
| [`posthog`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/posthog.md) | PostHog | SDK | Members removed in the posthog Python SDK 8.0.0 | `removedmembers` | [posthog-python 7.x to 8.0 migration guide](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) | live |
| [`newrelic`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/newrelic.md) | New Relic | SDK | Members removed in the New Relic Python agent 11.0.0 | `removedmembers` | [Python agent 11.0.0 release notes](https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx) | live |
| [`appwrite`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/appwrite.md) | Appwrite | API | REST API operations a server SDK calls that are deprecated between commits of the spec, SDK method renames left out | `openapi` | [appwrite/specs](https://github.com/appwrite/specs) (`specs/<X.Y>.x/open-api3-<X.Y>.x.json`, the newest minor) | live |
| [`salesforce`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/salesforce.md) | Salesforce | API | REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page | `eol` | [Salesforce API End-of-Life Policy](https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html) | live |
| [`flagsmith`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/flagsmith.md) | Flagsmith | API | REST API changes between releases of Flagsmith's own OpenAPI spec (removed endpoints and request parameters) | `openapi` | [github.com/Flagsmith/flagsmith/blob/main/openapi.yaml](https://github.com/Flagsmith/flagsmith/blob/main/openapi.yaml) | live |
<!-- plugins:end -->

Expand All @@ -48,7 +49,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe
| Provider | Whose API, SDK or package it is. |
| Layer | Which kind of dependency it covers: `API`, `SDK`, `package`, `runtime`, `CI` or `AI models`. |
| What it watches | The kind of change it reports, in a few words. |
| Format plugin | Which shared reader it is built on: `openapi` (a spec per release, diffed), `retirements` (a deprecations page), `migrationguide` (an SDK's migration guide), `removedmembers` (a package's table of removed members, in RST or Markdown), `changelog` (a release changelog file), `feed` (an RSS or Atom feed), `catalog` (a structured JSON catalog of names, diffed between two snapshots), `apichangelog` (a vendor's machine-readable API changelog, in JSON). |
| Format plugin | Which shared reader it is built on: `openapi` (a spec per release, diffed), `retirements` (a deprecations page), `migrationguide` (an SDK's migration guide), `removedmembers` (a package's table of removed members, in RST or Markdown), `changelog` (a release changelog file), `feed` (an RSS or Atom feed), `catalog` (a structured JSON catalog of names, diffed between two snapshots), `apichangelog` (a vendor's machine-readable API changelog, in JSON), `eol` (a vendor's own table of whole API version ranges and their support status). |
| Source | The provider's own public page or file the plugin reads. Every event links back to it. |
| Status | `live`: in the code on `main`. patch-it's hosted ingestion service runs it daily from the next release, which is cut automatically. `planned`: accepted, not written yet. `paused`: in the code but deliberately switched off, with the reason in the row. |

Expand Down
2 changes: 1 addition & 1 deletion docs/plugins.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
"provider": { "type": "string", "minLength": 1 },
"layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models"] },
"watches": { "type": "string", "minLength": 1 },
"format": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "removedmembers", "changelog", "feed", "apichangelog", "catalog"] },
"format": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "removedmembers", "changelog", "feed", "apichangelog", "catalog", "eol"] },
"source_url": { "type": "string", "pattern": "^https://" },
"status": { "type": "string", "enum": ["live", "paused", "planned"] },
"status_note": { "type": "string", "description": "Why, for a paused plugin." },
Expand Down
1 change: 1 addition & 0 deletions docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
| `plugins/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries |
| `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely |
| `plugins/apichangelog` | A vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), at the commit that last changed it | An `apichangelog.Log` |
| `plugins/eol` | A vendor's own table of whole API version ranges and their support status (supported, deprecated, retired) | An `eol.Page`; `--format` doesn't scaffold this one yet, write it by hand |

## 4. The interface

Expand Down
10 changes: 8 additions & 2 deletions plugin/plugin.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,14 @@ type Replayer interface {
// that client instead.
type Env struct {
Baselines BaselineReader
Get func(ctx context.Context, url string) ([]byte, error)
Now func() time.Time
// Get fetches one URL. In both the hosted ingestion service and the test
// kit, this is fetch.Cache.Get (kit/kittest's Pages.Get wraps saved files
// the same way): a non-2xx, non-304 response fails with a *fetch.StatusError
// naming the status, returned as is, so errors.As finds it. A plugin that
// branches on the status (eol, when the provider's own site blocks a plain
// GET) can rely on that.
Get func(ctx context.Context, url string) ([]byte, error)
Now func() time.Time
}

// BaselineReader is the one thing a plugin reads back: the baseline its last
Expand Down
1 change: 1 addition & 0 deletions plugins/all/all.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
_ "github.com/patch-it-dev/patch-it-plugins/plugins/apichangelog"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/catalog"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/changelog"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/eol"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/feed"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/openapi"
Expand Down
290 changes: 290 additions & 0 deletions plugins/eol/eol.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,290 @@
// Package eol is the source plugin for a vendor's own API end-of-life page: a
// table of whole version ranges, each with a support status. One event per
// version number a row says is already retired (breaking) or scheduled to be
// (deprecation); a row that only says "Supported." names nothing to report.
//
// There is no spec to diff, like retirements and feed: the page is read as it
// is now, and (as with them) the events cite a Wayback Machine snapshot of
// it, taken after a successful read of the live page, so the citation always
// says what the plugin actually saw.
//
// Salesforce's docs site is the one difference from retirements and feed: it
// answers 403 to a plain GET (checked 2026-11-20, including with a browser
// User-Agent), so Run's 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 Run falls back to a fresh snapshot on a 401 or 403,
// 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.
//
// 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
// replacement: moving up to any newer version clears it.
package eol

import (
"context"
"errors"
"fmt"
"log"
"regexp"
"strconv"
"strings"

"github.com/patch-it-dev/patch-it-plugins/event"
"github.com/patch-it-dev/patch-it-plugins/fetch"
"github.com/patch-it-dev/patch-it-plugins/kit"
"github.com/patch-it-dev/patch-it-plugins/plugin"
)

func init() {
plugin.Register(Plugin{Page: Salesforce, Archiver: kit.Wayback{}})
}

// Page is one vendor's end-of-life table.
type Page struct {
API string // the events' api: "salesforce"
Vendor string // for sentences: "Salesforce"
URL string // the page, as HTML
// Operation names the one real, documented, version-rooted resource a
// retired version takes down: Salesforce's "List Available REST
// Resources" call, GET /services/data/vXX.X/. Every other resource under
// that version is gone too (the page says so), but this is the one this
// plugin can point at honestly, without inventing a wildcard operation
// nothing calls.
Operation func(version string) string
}

// Salesforce is the REST API's end-of-life policy page (checked 2026-11-20):
// a table of version ranges, each "Supported.", already retired ("As of
// Summer '25, these versions are retired and unavailable."), or scheduled
// ("Deprecated and unsupported from Summer '27. Retired from Summer '28.").
// Salesforce gives no exact date, only the named release ("Summer '27"); the
// policy text above the table says the notice is at least a year ahead of
// retirement.
var Salesforce = Page{
API: "salesforce", Vendor: "Salesforce",
URL: "https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html",
Operation: func(v string) string { return "GET /services/data/v" + v + "/" },
}

// Row is one version range and what its status cell says, cleaned of HTML.
type Row struct {
From, To int // inclusive, both ends; From == To for a single version
Label string // the first cell's own text, word for word ("Versions 31.0 through 40.0")
Status string // every <p> in the status cell, joined with a space
}

// Finding is one version number a row's status names, or a row that names
// none (Dropped set).
type Finding struct {
ChangeType event.ChangeType
Version string // "21.0"
Season string // "Summer ’25", or "Summer ’27, retired from Summer ’28"
Excerpt string
Row string // the row's version-range text, for Dropped's log line
Dropped string
}

var (
table = regexp.MustCompile(`(?is)<tbody>(.*?)</tbody>`)
row = regexp.MustCompile(`(?is)<tr>(.*?)</tr>`)
// cell tolerates an attribute (<td class="…">): a future style change
// shouldn't make every row unreadable.
cell = regexp.MustCompile(`(?is)<td[^>]*>(.*?)</td>`)
tag = regexp.MustCompile(`<[^>]+>`)
// versions reads only the whole-number part of a version ("31.0 through
// 40.0" -> 31, 40): every version on the page today is a whole number.
// Salesforce has never shipped a minor REST API version, but this would
// silently drop one ("31.5") rather than fail loudly if that changed.
versions = regexp.MustCompile(`(?i)Versions?\s+(\d+)(?:\.\d+)?(?:\s+through\s+(\d+)(?:\.\d+)?)?`)
retired = regexp.MustCompile(`(?i)As of ([^,]+), these versions are retired and unavailable\.`)
deprecd = regexp.MustCompile(`(?i)Deprecated and unsupported from ([^.]+)\.\s*Retired from ([^.]+)\.`)
)

// text strips tags and normalizes whitespace, the way a <td>'s content (bare
// text, or several <p>s) reads as one sentence.
func text(fragment string) string {
return strings.Join(strings.Fields(tag.ReplaceAllString(fragment, " ")), " ")
}

// Parse reads every row of the page's first table.
func Parse(page []byte) ([]Row, error) {
m := table.FindStringSubmatch(string(page))
if m == nil {
return nil, fmt.Errorf("no table found: the page's shape may have changed")
}
var out []Row
for _, r := range row.FindAllStringSubmatch(m[1], -1) {
cells := cell.FindAllStringSubmatch(r[1], -1)
if len(cells) < 2 {
continue
}
label := text(cells[0][1])
vm := versions.FindStringSubmatch(label)
if vm == nil {
continue
}
from, _ := strconv.Atoi(vm[1])
to := from
if vm[2] != "" {
to, _ = strconv.Atoi(vm[2])
}
out = append(out, Row{From: from, To: to, Label: label, Status: text(cells[1][1])})
}
if len(out) == 0 {
return nil, fmt.Errorf("no version rows found: the page's shape may have changed")
}
return out, nil
}

// Findings classifies every row and names every version number a breaking or
// deprecated row covers. A row that's merely "Supported." names none.
func Findings(page []byte) ([]Finding, error) {
rows, err := Parse(page)
if err != nil {
return nil, err
}
var out []Finding
for _, r := range rows {
label := r.Label
excerpt := label + " | " + r.Status

var ct event.ChangeType
var season string
switch {
case retired.MatchString(r.Status):
ct, season = event.ChangeTypeBreaking, retired.FindStringSubmatch(r.Status)[1]
case deprecd.MatchString(r.Status):
m := deprecd.FindStringSubmatch(r.Status)
ct, season = event.ChangeTypeDeprecation, m[1]+", retired from "+m[2]
default:
out = append(out, Finding{Row: label, Dropped: fmt.Sprintf("status %q names neither a retirement nor a deprecation", r.Status)})
continue
}
for v := r.From; v <= r.To; v++ {
out = append(out, Finding{
ChangeType: ct,
Version: fmt.Sprintf("%d.0", v),
Season: season,
Excerpt: excerpt,
Row: label,
})
}
}
return out, nil
}

// Plugin reads one vendor's end-of-life page.
type Plugin struct {
Page Page
Archiver kit.Archiver
}

func (p Plugin) Name() string { return p.Page.API }

// Run reads the page as it is now. An unchanged page since the last run costs
// one GET and no snapshot, unless the live page is blocked: see liveOrArchived.
func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) {
pg := p.Page
live, archived, err := liveOrArchived(ctx, env, p.Archiver, pg.URL)
if err != nil {
return plugin.Result{}, fmt.Errorf("fetching %s: %w", pg.URL, err)
}
hash := plugin.SHA256(live)
last, same, err := kit.Unchanged(env, pg.API, live)
if err != nil {
return plugin.Result{}, err
}
if same {
log.Printf("%s: no change since %s", pg.API, last.SourceURL)
return plugin.Result{}, nil
}

want, err := Findings(live)
if err != nil {
return plugin.Result{}, fmt.Errorf("reading %s: %w", pg.URL, err)
}

snapURL, snap, got := archived, live, want
if snapURL == "" {
snapURL, snap, got, err = kit.Cite(ctx, p.Archiver, pg.URL, Findings, want)
if err != nil {
return plugin.Result{}, err
}
}

now := env.Now().UTC()
var events []event.EventV2
var rejected []error
for _, f := range got {
if f.Dropped != "" {
log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped)
continue
}
e := event.EventV2{
API: pg.API,
Version: f.Version,
ChangeType: f.ChangeType,
Breaking: f.ChangeType == event.ChangeTypeBreaking,
Subject: event.Subject{
Type: event.SubjectAPIOperation,
Kind: event.AffectedKindOperation,
Side: event.SideRequest,
Operation: pg.Operation(f.Version),
},
Description: describe(pg, f),
MigrationHint: fmt.Sprintf("Pin a newer %s REST API version: %s names which ones are still supported.", pg.Vendor, snapURL),
SourceURL: snapURL,
SourceExcerpt: f.Excerpt,
Confidence: 1.0,
DetectedAt: now,
}
e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "")
if err := e.Validate(); err != nil {
rejected = append(rejected, fmt.Errorf("%s %s: %w", pg.API, f.Version, err))
continue
}
events = append(events, e)
}
baseline := plugin.Baseline(pg.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now)
baseline.SHA256 = hash
return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil
}

// liveOrArchived reads pageURL directly. When 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 this exact 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.
func liveOrArchived(ctx context.Context, env plugin.Env, a kit.Archiver, pageURL string) (body []byte, archivedURL string, err error) {
body, err = env.Get(ctx, pageURL)
if err == nil {
return body, "", nil
}
var se *fetch.StatusError
if !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) {
return nil, "", err
}
archivedURL, body, archErr := a.Snapshot(ctx, pageURL)
if archErr != nil {
return nil, "", fmt.Errorf("fetching it directly failed (%w), and so did asking the Wayback Machine to: %w", err, archErr)
}
return body, archivedURL, nil
}

func describe(pg Page, f Finding) string {
if f.ChangeType == event.ChangeTypeBreaking {
return fmt.Sprintf("%s REST API version %s is retired, as of %s: it returns 410:GONE for every resource.", pg.Vendor, f.Version, f.Season)
}
return fmt.Sprintf("%s REST API version %s is deprecated and scheduled for retirement: unsupported from %s.", pg.Vendor, f.Version, f.Season)
}
Loading
Loading