Skip to content

feat: add availability persistence foundation - #834

Draft
nrlcode wants to merge 3 commits into
javi11:mainfrom
nrlcode:feat/availability-foundation
Draft

feat: add availability persistence foundation#834
nrlcode wants to merge 3 commits into
javi11:mainfrom
nrlcode:feat/availability-foundation

Conversation

@nrlcode

@nrlcode nrlcode commented Aug 22, 2026

Copy link
Copy Markdown

What this PR is for

This PR lays the persistence and identity foundation for a later latency improvement: remembering which files and articles are available from the configured provider pool, so future import, health, and streaming paths can avoid repeating futile work.

It is intentionally a foundation-only change. It does not change importer behavior, health scheduling, streaming, first-byte latency, or article reads yet. Later PRs will add writers and consumers only after the provider-identity and failure-taxonomy decisions are confirmed.

What changes

  • Add non-secret, aggregate active-provider-pool scope identity and generation handling.
  • Add canonical v1 manifest identity from resolved main-file SegmentData.
  • Add fail-closed eligibility rules for unsafe main-file metadata while ignoring ordinary PAR2 sidecars.
  • Add reversible SQLite/PostgreSQL migration 035 for TTL-aware availability facts.
  • Add idempotent AvailabilityRepository operations for definitive manifest-present summaries and confirmed-missing article facts.
  • Wire the repository into database construction without adding production callers.

What this deliberately does not change

  • No import-validation writers or scheduled-health writers.
  • No streaming/open/read changes, STAT look-ahead, hot cache, BodyPriority, fallback, or repair behavior.
  • No changes to file_health, .meta, KnownHoles, segcache, public config/API, metrics, or scheduler behavior.
  • No per-provider availability persistence and no article-body persistence.
  • Unknown, transient, cancellation, authentication, provider-pool, and body-integrity uncertainty are not persisted as confirmed absence.

Verification

Passed:

  • go test ./internal/availability ./internal/database -count=1
  • go test -race ./internal/availability ./internal/database -count=1
  • targeted migration/repository tests
  • v3 metadata resolution test
  • go vet ./internal/availability ./internal/database
  • go build ./...
  • gofmt and git diff --check

Independent audits:

  • Terra auditor: PASS (t_3ecd55d5)
  • Independent Grok 4.6 auditor: PASS (t_183ac982)

Known bounded caveats:

  • Live PostgreSQL execution was not run because the repository has no supported PostgreSQL test DSN/service/CI convention. Both dialect migration files received static contract-parity checks; no test credentials or infrastructure were invented.
  • The full-suite metadata directory-mtime failure and existing API lint findings remain outside this PR and were reproduced independently of this change.

Follow-up sequence

  • Next candidate PR: import-validation and scheduled-health writers, after the provider-identity and failure-taxonomy decisions are confirmed.
  • Later candidate PR: streaming consumption and bounded asynchronous STAT look-ahead, preserving first-byte delivery.
  • Optional policy/API/observability only if real integration evidence requires it.

@nrlcode

nrlcode commented Aug 23, 2026

Copy link
Copy Markdown
Author

Don't merge this yet, probably will change or revoke this.

@javi11

javi11 commented Aug 23, 2026

Copy link
Copy Markdown
Owner

Not sure why we should do this

@javi11
javi11 marked this pull request as draft August 23, 2026 18:27
@nrlcode

nrlcode commented Aug 23, 2026

Copy link
Copy Markdown
Author

Yes I'll probably keep this in draft for now. What I am trying to do is create a provider availability / segment map. If your primary has a lot of missing articles but your backups have them, streaming can be quite slow. On 4k web-dls I get a lot of buffering because of this. It's running fast, hits a missing articles, has to go and fetch it. This slows the whole pipeline down if it happens frequently.

So the goal would be to do a few things:

  1. anytime segments are checked (health checks, imports, streaming) we would store which providers had which segment. This would probably be some sort of sparse map.
  2. when streaming, if there is evidence, then body requests prioritize the provider known for having each segment.
  3. if the map doesn't exist or is stale, then streaming proceeds as normal. However, if it starts to encounter a lot of missing articles, it would dispatch a health read ahead and build the map out for the file so that streaming doesn't get hosed.

There are a lot of blockers currently for this though because of how altmount / nntppool handles provider ids, multiple primaries in round robin, etc...

This PR was to lay some of the foundation work but I will be amending it in the future with some more narrowly scoped changes.

Do you think this is a useful feature? It's something I run into regularly and I am assuming it is the cause of my slow streaming in certain instances.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants