polling without ETags spends full quota on unchanged data

"""Measure what conditional requests would save against the GitHub rate limit.

Read only. Two GETs against one endpoint: the second sends If-None-Match with the
ETag the first returned. A 304 Not Modified does not count against the primary
rate limit, and x-ratelimit-used on both responses proves it rather than
asserting it.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("github_etag_saving")

API = "https://api.github.com"
UA = "github-etag-saving/1.0"

DEFAULT_LIMIT = 5000


def measure(first, second):
    """Compare a plain response with the conditional one that followed. Pure.

    Each argument is {"status": int, "etag": str|None, "used": int|None}. Returns
    (state, report). The states are deliberately separate because they have
    nothing in common: an endpoint that sends no ETag cannot be cached at all, an
    endpoint that answers 200 to a conditional request is being interfered with,
    and a 304 that still increments used would mean the documented discount did
    not apply.
    """
    etag = (first or {}).get("etag")
    before = (first or {}).get("used")
    after = (second or {}).get("used")
    status = (second or {}).get("status")

    try:
        delta = int(after) - int(before)
    except (TypeError, ValueError):
        delta = None

    report = {"etag": etag, "used_before": before, "used_after": after,
              "cost_of_unchanged_poll": delta,
              "first_status": (first or {}).get("status"), "second_status": status}

    if not etag:
        return ("no-etag", report)
    if status != 304:
        return ("not-honoured", report)
    if delta is None:
        return ("unmeasured", report)
    if delta > 0:
        return ("billed", report)
    return ("free", report)


def project(poll_seconds, endpoints, limit=DEFAULT_LIMIT, unchanged_fraction=1.0):
    """Price a polling schedule with and without conditional requests. Pure.

    unchanged_fraction is how much of what you poll is typically unchanged. At
    1.0 every poll is a 304 and costs nothing; at 0.0 nothing is cacheable and
    conditional requests save nothing, which is the honest end of the range.
    """
    poll_seconds = max(1.0, float(poll_seconds))
    endpoints = max(1, int(endpoints))
    limit = max(1, int(limit))
    fraction = min(1.0, max(0.0, float(unchanged_fraction)))

    without = (3600.0 / poll_seconds) * endpoints
    with_etags = without * (1.0 - fraction)
    return {"per_hour_without": round(without, 1),
            "per_hour_with": round(with_etags, 1),
            "saved_per_hour": round(without - with_etags, 1),
            "percent_without": round(100.0 * without / limit, 1),
            "percent_with": round(100.0 * with_etags / limit, 1),
            "limit": limit}


def verdict(state, projection):
    """Turn the measurement and the projection into one line. Pure."""
    saved = (projection or {}).get("saved_per_hour", 0)
    percent = (projection or {}).get("percent_without", 0)

    if state == "no-etag":
        return ("unavailable",
                "the response carried no etag, so this endpoint cannot be polled "
                "conditionally. Check last-modified and use if-modified-since "
                "where it is present.")
    if state == "not-honoured":
        return ("ignored",
                "the conditional request came back 200 rather than 304. Either "
                "the resource genuinely changed between the two calls, or "
                "something between this client and GitHub is dropping the "
                "If-None-Match header, which silently reinstates the full cost.")
    if state == "billed":
        return ("billed",
                "the 304 arrived and x-ratelimit-used still moved, which is not "
                "how conditional requests are documented to behave. Re-run "
                "before acting on it: another process sharing this token spends "
                "the same counter.")
    if state == "unmeasured":
        return ("unmeasured",
                "the 304 arrived but x-ratelimit-used was missing from one of "
                "the responses, so the saving is real and its size is not "
                "measured here.")
    return ("saving" if percent < 25 else "large-saving",
            "the 304 cost 0 request(s). At this poll rate that is %.0f request(s) "
            "an hour, %.1f%% of the quota, currently spent on data that did not "
            "change." % (saved, percent))


def read(response):
    """Reduce a response to the three fields the measurement needs."""
    headers = {k.lower(): v for k, v in response.headers.items()}
    try:
        used = int(headers.get("x-ratelimit-used"))
    except (TypeError, ValueError):
        used = None
    return {"status": response.status_code, "etag": headers.get("etag"),
            "used": used, "last_modified": headers.get("last-modified"),
            "limit": headers.get("x-ratelimit-limit")}


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--repo", required=True, help="owner/name")
    ap.add_argument("--path", default="/issues",
                    help="path under the repository to probe, e.g. /issues")
    ap.add_argument("--poll-seconds", type=float, default=60.0,
                    help="how often your integration polls this endpoint")
    ap.add_argument("--endpoints", type=int, default=1,
                    help="how many endpoints are polled on that schedule")
    ap.add_argument("--unchanged", type=float, default=1.0,
                    help="fraction of polls that find nothing changed (0 to 1)")
    args = ap.parse_args()

    token = os.environ.get("GITHUB_TOKEN")
    if not token:
        log.error("set GITHUB_TOKEN (a read-only token is enough)")
        return 2

    owner, _, name = args.repo.partition("/")
    if not (owner and name):
        log.error("--repo takes owner/name, for example acme/api")
        return 2

    session = requests.Session()
    session.headers.update({
        "Authorization": "Bearer " + token,
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "User-Agent": UA,
    })

    url = "%s/repos/%s/%s%s" % (API, owner, name, args.path)
    log.info("probing %s twice: once plain, once with If-None-Match", url)

    plain = session.get(url, timeout=30)
    if plain.status_code == 401:
        log.error("401 from GitHub: GITHUB_TOKEN is missing, expired or malformed")
        return 2
    if plain.status_code in (403, 404):
        log.error("%d from %s: this token cannot read that endpoint. GitHub "
                  "answers 404 rather than 403 when a token cannot see a "
                  "resource at all.", plain.status_code, url)
        return 2
    first = read(plain)
    log.info("  plain:       %d, etag %s, x-ratelimit-used %s",
             first["status"], first["etag"], first["used"])

    second = first
    if first["etag"]:
        conditional = session.get(url, timeout=30,
                                  headers={"If-None-Match": first["etag"]})
        second = read(conditional)
        log.info("  conditional: %d, x-ratelimit-used %s",
                 second["status"], second["used"])
    elif first["last_modified"]:
        log.warning("  no etag, but last-modified is %s: use if-modified-since "
                    "on this endpoint instead", first["last_modified"])

    state, report = measure(first, second)
    limit = DEFAULT_LIMIT
    try:
        limit = int(first["limit"])
    except (TypeError, ValueError):
        pass

    projection = project(args.poll_seconds, args.endpoints, limit, args.unchanged)
    level, detail = verdict(state, projection)
    log.info("%s: %s", level, detail)
    log.info("  %.0f request(s)/hour now (%.1f%% of %d), %.0f/hour with "
             "conditional requests (%.1f%%)",
             projection["per_hour_without"], projection["percent_without"],
             projection["limit"], projection["per_hour_with"],
             projection["percent_with"])

    if level in ("saving", "large-saving"):
        log.info("  repair: store %s against this exact URL and credential, send "
                 "it back as If-None-Match, and treat 304 as 'keep what you "
                 "have' rather than as an error.", report["etag"])
        log.info("  repair: keep per_page, sort and Accept stable, and key the "
                 "cache by token: an ETag is scoped to the credential that "
                 "fetched it, so a rotation invalidates every entry at once.")
    return 0 if level in ("saving", "large-saving", "unavailable") else 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Measure what conditional requests would save against the GitHub rate limit.
 *
 * Read only. Two GETs against one endpoint: the second sends If-None-Match with
 * the ETag the first returned. A 304 Not Modified does not count against the
 * primary rate limit, and x-ratelimit-used on both responses proves it.
 */
const API = 'https://api.github.com';
const UA = 'github-etag-saving/1.0';

export const DEFAULT_LIMIT = 5000;

/**
 * Compare a plain response with the conditional one that followed. Pure.
 * Each argument is { status, etag, used }. Returns [state, report].
 */
export function measure(first, second) {
  const etag = first?.etag ?? null;
  const before = first?.used;
  const after = second?.used;
  const status = second?.status;

  const parsedBefore = Number.parseInt(before, 10);
  const parsedAfter = Number.parseInt(after, 10);
  const delta = (Number.isFinite(parsedBefore) && Number.isFinite(parsedAfter))
    ? parsedAfter - parsedBefore : null;

  const report = {
    etag,
    used_before: before ?? null,
    used_after: after ?? null,
    cost_of_unchanged_poll: delta,
    first_status: first?.status ?? null,
    second_status: status ?? null,
  };

  if (!etag) return ['no-etag', report];
  if (status !== 304) return ['not-honoured', report];
  if (delta === null) return ['unmeasured', report];
  if (delta > 0) return ['billed', report];
  return ['free', report];
}

/**
 * Price a polling schedule with and without conditional requests. Pure.
 * unchangedFraction is how much of what you poll is typically unchanged.
 */
export function project(pollSeconds, endpoints, limit = DEFAULT_LIMIT, unchangedFraction = 1) {
  const seconds = Math.max(1, Number(pollSeconds));
  const count = Math.max(1, Math.trunc(endpoints));
  const cap = Math.max(1, Math.trunc(limit));
  const fraction = Math.min(1, Math.max(0, Number(unchangedFraction)));

  const without = (3600 / seconds) * count;
  const withEtags = without * (1 - fraction);
  const round = (n) => Math.round(n * 10) / 10;
  return {
    per_hour_without: round(without),
    per_hour_with: round(withEtags),
    saved_per_hour: round(without - withEtags),
    percent_without: round(100 * without / cap),
    percent_with: round(100 * withEtags / cap),
    limit: cap,
  };
}

/** Turn the measurement and the projection into one line. Pure. */
export function verdict(state, projection) {
  const saved = projection?.saved_per_hour ?? 0;
  const percent = projection?.percent_without ?? 0;

  if (state === 'no-etag') {
    return ['unavailable',
      'the response carried no etag, so this endpoint cannot be polled ' +
      'conditionally. Check last-modified and use if-modified-since where it ' +
      'is present.'];
  }
  if (state === 'not-honoured') {
    return ['ignored',
      'the conditional request came back 200 rather than 304. Either the ' +
      'resource genuinely changed between the two calls, or something between ' +
      'this client and GitHub is dropping the If-None-Match header, which ' +
      'silently reinstates the full cost.'];
  }
  if (state === 'billed') {
    return ['billed',
      'the 304 arrived and x-ratelimit-used still moved, which is not how ' +
      'conditional requests are documented to behave. Re-run before acting on ' +
      'it: another process sharing this token spends the same counter.'];
  }
  if (state === 'unmeasured') {
    return ['unmeasured',
      'the 304 arrived but x-ratelimit-used was missing from one of the ' +
      'responses, so the saving is real and its size is not measured here.'];
  }
  return [percent < 25 ? 'saving' : 'large-saving',
    `the 304 cost 0 request(s). At this poll rate that is ${Math.round(saved)} ` +
    `request(s) an hour, ${percent}% of the quota, currently spent on data that ` +
    'did not change.'];
}

function read(res) {
  const headers = {};
  for (const [k, v] of res.headers.entries()) headers[k.toLowerCase()] = v;
  const used = Number.parseInt(headers['x-ratelimit-used'], 10);
  return {
    status: res.status,
    etag: headers.etag ?? null,
    used: Number.isFinite(used) ? used : null,
    last_modified: headers['last-modified'] ?? null,
    limit: headers['x-ratelimit-limit'] ?? null,
  };
}

function head(token, extra = {}) {
  return {
    Authorization: `Bearer ${token}`,
    Accept: 'application/vnd.github+json',
    'X-GitHub-Api-Version': '2022-11-28',
    'User-Agent': UA,
    ...extra,
  };
}

async function main() {
  const repo = process.argv[2];
  const path = process.argv[3] ?? '/issues';
  const pollSeconds = Number.parseFloat(process.argv[4] ?? '60') || 60;
  const endpoints = Number.parseInt(process.argv[5] ?? '1', 10) || 1;
  const token = process.env.GITHUB_TOKEN;

  if (!token) {
    console.error('set GITHUB_TOKEN (a read-only token is enough)');
    process.exitCode = 2;
    return;
  }
  if (!repo || !repo.includes('/')) {
    console.error('usage: node github-etag-saving.mjs owner/name [/path] ' +
      '[pollSeconds] [endpoints]');
    process.exitCode = 2;
    return;
  }

  const url = `${API}/repos/${repo}${path}`;
  console.log(`probing ${url} twice: once plain, once with If-None-Match`);

  const plain = await fetch(url, { headers: head(token) });
  if (plain.status === 401) {
    console.error('401 from GitHub: GITHUB_TOKEN is missing, expired or malformed');
    process.exitCode = 2;
    return;
  }
  if (plain.status === 403 || plain.status === 404) {
    console.error(`${plain.status} from ${url}: this token cannot read that ` +
      'endpoint. GitHub answers 404 rather than 403 when a token cannot see a ' +
      'resource at all.');
    process.exitCode = 2;
    return;
  }
  const first = read(plain);
  console.log(`  plain:       ${first.status}, etag ${first.etag}, ` +
    `x-ratelimit-used ${first.used}`);

  let second = first;
  if (first.etag) {
    const conditional = await fetch(url, {
      headers: head(token, { 'If-None-Match': first.etag }),
    });
    second = read(conditional);
    console.log(`  conditional: ${second.status}, x-ratelimit-used ${second.used}`);
  } else if (first.last_modified) {
    console.warn(`  no etag, but last-modified is ${first.last_modified}: use ` +
      'if-modified-since on this endpoint instead');
  }

  const [state, report] = measure(first, second);
  const limit = Number.parseInt(first.limit, 10) || DEFAULT_LIMIT;
  const projection = project(pollSeconds, endpoints, limit, 1);
  const [level, detail] = verdict(state, projection);
  console.log(`${level}: ${detail}`);
  console.log(`  ${projection.per_hour_without} request(s)/hour now ` +
    `(${projection.percent_without}% of ${projection.limit}), ` +
    `${projection.per_hour_with}/hour with conditional requests ` +
    `(${projection.percent_with}%)`);

  if (level === 'saving' || level === 'large-saving') {
    console.log(`  repair: store ${report.etag} against this exact URL and ` +
      "credential, send it back as If-None-Match, and treat 304 as 'keep what " +
      "you have' rather than as an error.");
    console.log('  repair: keep per_page, sort and Accept stable, and key the ' +
      'cache by token: an ETag is scoped to the credential that fetched it, so ' +
      'a rotation invalidates every entry at once.');
  }
  process.exitCode = ['saving', 'large-saving', 'unavailable'].includes(level) ? 0 : 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing token, and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from github_etag_saving import measure, project, verdict

ETAG = 'W/"6c1a2f9e0b7d4a3c"'


def response(status, etag=ETAG, used=None):
    return {"status": status, "etag": etag, "used": used}


def test_a_304_that_did_not_move_the_counter_is_the_finding():
    state, report = measure(response(200, used=101), response(304, used=101))
    assert state == "free"
    assert report["cost_of_unchanged_poll"] == 0
    assert report["etag"] == ETAG


def test_an_endpoint_with_no_etag_cannot_be_polled_conditionally():
    state, _ = measure(response(200, etag=None, used=10), response(200, used=11))
    assert state == "no-etag"


def test_a_200_answer_to_a_conditional_request_is_its_own_finding():
    # A proxy that strips If-None-Match reinstates the full cost silently.
    state, report = measure(response(200, used=10), response(200, used=11))
    assert state == "not-honoured"
    assert report["cost_of_unchanged_poll"] == 1


def test_a_304_that_still_billed_is_reported_rather_than_smoothed_over():
    state, report = measure(response(200, used=10), response(304, used=12))
    assert state == "billed"
    assert report["cost_of_unchanged_poll"] == 2


def test_a_missing_used_header_leaves_the_saving_unmeasured():
    state, report = measure(response(200, used=None), response(304, used=None))
    assert state == "unmeasured"
    assert report["cost_of_unchanged_poll"] is None


def test_the_projection_prices_a_real_polling_schedule():
    p = project(30, 8, 5000, 1.0)
    assert p["per_hour_without"] == 960.0
    assert p["per_hour_with"] == 0.0
    assert p["saved_per_hour"] == 960.0
    assert p["percent_without"] == 19.2


def test_a_partly_changing_workload_saves_only_part_of_it():
    p = project(60, 1, 5000, 0.75)
    assert p["per_hour_without"] == 60.0
    assert p["per_hour_with"] == 15.0
    assert p["saved_per_hour"] == 45.0


def test_nothing_unchanged_means_nothing_saved():
    p = project(60, 1, 5000, 0.0)
    assert p["saved_per_hour"] == 0.0


def test_the_projection_refuses_nonsense_inputs_instead_of_dividing_by_zero():
    p = project(0, 0, 0, 5.0)
    assert p["limit"] == 1
    assert p["per_hour_without"] == 3600.0
    assert p["per_hour_with"] == 0.0


def test_a_large_share_of_quota_is_called_out_as_such():
    level, detail = verdict("free", project(30, 8, 5000, 1.0))
    assert level == "saving"
    assert "19.2%" in detail
    assert verdict("free", project(10, 8, 5000, 1.0))[0] == "large-saving"


def test_each_unhappy_state_names_a_different_repair():
    assert verdict("no-etag", project(60, 1))[0] == "unavailable"
    assert verdict("not-honoured", project(60, 1))[0] == "ignored"
    assert verdict("billed", project(60, 1))[0] == "billed"
    assert verdict("unmeasured", project(60, 1))[0] == "unmeasured"


def test_the_ignored_state_blames_the_header_not_the_quota():
    _, detail = verdict("not-honoured", project(60, 1))
    assert "If-None-Match" in detail


def test_the_billed_state_points_at_the_shared_counter():
    _, detail = verdict("billed", project(60, 1))
    assert "shares" in detail or "sharing" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { measure, project, verdict } from './github-etag-saving.mjs';

const ETAG = 'W/"6c1a2f9e0b7d4a3c"';

const response = (status, etag = ETAG, used = null) => ({ status, etag, used });

test('a 304 that did not move the counter is the finding', () => {
  const [state, report] = measure(response(200, ETAG, 101), response(304, ETAG, 101));
  assert.equal(state, 'free');
  assert.equal(report.cost_of_unchanged_poll, 0);
  assert.equal(report.etag, ETAG);
});

test('an endpoint with no etag cannot be polled conditionally', () => {
  const [state] = measure(response(200, null, 10), response(200, ETAG, 11));
  assert.equal(state, 'no-etag');
});

test('a 200 answer to a conditional request is its own finding', () => {
  const [state, report] = measure(response(200, ETAG, 10), response(200, ETAG, 11));
  assert.equal(state, 'not-honoured');
  assert.equal(report.cost_of_unchanged_poll, 1);
});

test('a 304 that still billed is reported rather than smoothed over', () => {
  const [state, report] = measure(response(200, ETAG, 10), response(304, ETAG, 12));
  assert.equal(state, 'billed');
  assert.equal(report.cost_of_unchanged_poll, 2);
});

test('a missing used header leaves the saving unmeasured', () => {
  const [state, report] = measure(response(200, ETAG, null), response(304, ETAG, null));
  assert.equal(state, 'unmeasured');
  assert.equal(report.cost_of_unchanged_poll, null);
});

test('the projection prices a real polling schedule', () => {
  const p = project(30, 8, 5000, 1);
  assert.equal(p.per_hour_without, 960);
  assert.equal(p.per_hour_with, 0);
  assert.equal(p.saved_per_hour, 960);
  assert.equal(p.percent_without, 19.2);
});

test('a partly changing workload saves only part of it', () => {
  const p = project(60, 1, 5000, 0.75);
  assert.equal(p.per_hour_without, 60);
  assert.equal(p.per_hour_with, 15);
  assert.equal(p.saved_per_hour, 45);
});

test('nothing unchanged means nothing saved', () => {
  assert.equal(project(60, 1, 5000, 0).saved_per_hour, 0);
});

test('the projection refuses nonsense inputs instead of dividing by zero', () => {
  const p = project(0, 0, 0, 5);
  assert.equal(p.limit, 1);
  assert.equal(p.per_hour_without, 3600);
  assert.equal(p.per_hour_with, 0);
});

test('a large share of quota is called out as such', () => {
  const [level, detail] = verdict('free', project(30, 8, 5000, 1));
  assert.equal(level, 'saving');
  assert.match(detail, /19\.2%/);
  assert.equal(verdict('free', project(10, 8, 5000, 1))[0], 'large-saving');
});

test('each unhappy state names a different repair', () => {
  assert.equal(verdict('no-etag', project(60, 1))[0], 'unavailable');
  assert.equal(verdict('not-honoured', project(60, 1))[0], 'ignored');
  assert.equal(verdict('billed', project(60, 1))[0], 'billed');
  assert.equal(verdict('unmeasured', project(60, 1))[0], 'unmeasured');
});

test('the ignored state blames the header, not the quota', () => {
  assert.match(verdict('not-honoured', project(60, 1))[1], /If-None-Match/);
});

test('the billed state points at the shared counter', () => {
  assert.match(verdict('billed', project(60, 1))[1], /shar/);
});