Skip to content

Modify PUT to allow modification of fields - #73

Merged
JackLewis-digirati merged 5 commits into
mainfrom
feature/reprocessPdfCoverpage
Nov 6, 2026
Merged

JackLewis-digirati merged 5 commits into
mainfrom
feature/reprocessPdfCoverpage

Conversation

@JackLewis-digirati

@JackLewis-digirati JackLewis-digirati commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

This PR modifies how PUT works to allow modification. This was built to support dlcs/iiif-presentation#704 where the cover page and capabilities can now change between pushes.

Additionally, this PR supports the generation of PDF's which have no text resources. Prior to this, at least 1 text resource was required in order to generate a PDF. This will now allow it regardless of the text pipelines.

@JackLewis-digirati
JackLewis-digirati force-pushed the feature/reprocessPdfCoverpage branch from 3619dfd to b8e5bbb Compare October 22, 2026 09:24
@JackLewis-digirati

Copy link
Copy Markdown
Contributor Author

Builds on #72 (base branch feature/pdfCoverpage). Motivated by dlcs/iiif-presentation#704.

What this does

  1. PUT /textbuilder/{id} can take a body that replaces the job's definition (e.g. to change or remove a cover page, or change services), not just reprocess it.
  2. PDFs can be generated for jobs that have no text, as image-only pages.
  3. PDF requests check the stored Manifest exists with a cheap existence check rather than downloading it.

No database migration or configuration changes.


1. PUT with a body replaces the job definition

Problem: iiif-presentation POSTs a job and, on 409, falls back to PUT /textbuilder/{id}. That endpoint ignored any body and reprocessed the stored job, so changes (cover page, services, etc.) never reached text-services, and a cover page added via #72 could never be removed. Deleting and re-POSTing isn't an option because it resets invocationCount, which iiif-presentation uses to match completion notifications.

Behaviour:

  • No body — unchanged: the stored job is reprocessed.
  • With a body — standard PUT semantics:
    • The body is a complete job definition, in the same format and with the same validation as POST.
    • Its id must match the URL (400 otherwise); the id is the only thing that can't change.
    • sourceUri, sourceData, services, title and customTypes are all replaced. Omitted fields are reset to their defaults, not kept — e.g. omitting sourceData removes inserted PDFs, and omitting services enables all services.
    • A job can switch between sourceUri and sourceData.
  • invocationCount is incremented on every reprocess, with or without a body. A Running job still returns 409 and is left unchanged.

Implementation: the instruction→job mapping is now JobInstruction.ApplyTo(BuilderJob), shared by POST (CreateJob) and PUT (ReprocessJob). POST and PUT share the validation helper in JobEndpoints. For sourceUri jobs, applying a body replaces the stored SourceDataJson (including the reduced page list from the previous run), so only pdf entries in the new body survive.

2. PDFs without text

Previously a job with no indexed words got no PDF at all: Pdf was only marked fulfilled when a Text artefact was saved, and the Search API required the Text artefact. Since #72 renders canvases without text as image-only pages, that restriction no longer makes sense.

  • Builder (TextBuildJob): Pdf is fulfilled when it was requested, the Manifest was saved, and at least one page can be rendered — an image canvas (has an image URI and no duration, so not audio/video), an inserted PDF, or a custom-type page. Text is not required, and no empty Text artefact is stored. Search still requires text.
  • Search API (PdfQuery, PdfGenerationService): GET/POST /rendering/pdf/v1/{id} require the stored Manifest instead of the Text artefact. With no Text artefact, generation uses an empty index, so every page is image-only.
  • Text-augmented Manifest: the PDF rendering link is added when the Pdf service is enabled and the Manifest has an image canvas, even when there's no text (in which case there's no plain-text link or search services).

3. ITextStore.ManifestExists

Switching the PDF check from the Text artefact to the Manifest would otherwise have meant downloading the whole Manifest (potentially several MB) on every request for a not-yet-generated PDF — and twice on first generation.

  • New ITextStore.ManifestExists(key). The interface has a default implementation (loads the Manifest), so test stubs are unaffected.
  • S3TextStore uses a HEAD request: the existing Exists logic was extracted into a private ObjectExists(key, fileName) shared by Exists and ManifestExists.
  • FileSystemTextStore uses File.Exists.

Points to note

  • PDF link now respects the Pdf capability. Previously the text-augmented Manifest added a PDF link for any job with text on an image canvas, even if Pdf wasn't enabled (the link then 404ed). Jobs without a capabilities file are treated as all-enabled, so they're unaffected.
  • Existing jobs without text don't gain a PDF automatically — they need reprocessing so Pdf is marked fulfilled.
  • More PDF generation load: items with no text now produce PDFs. Each first request fetches every page image and renders it, so expect more generation and stored PDFs if there are many image-only items.
  • GET /rendering/pdf/v1/{id} and POST now 404 when there's no stored Manifest, Pdf isn't enabled, or there are no image canvases — rather than "no text index".

Tests & docs

  • ReprocessJobTests (new): no body keeps the definition; body replaces inserted PDFs, replaces all fields, resets omitted fields, switches a sourceData job to sourceUri; 409 for running jobs; 404 for unknown jobs.
  • TextBuildJobTests: no text + image canvas → Pdf fulfilled with no Text artefact stored; AV-only → no Pdf.
  • PdfHandlerTests: the stub store now has a Manifest but never text, so every test runs without text; "no text" tests became "no Manifest" tests.
  • TextAugmentedHandlerTests: no text + image canvas → PDF link only; Pdf disabled → no PDF link.
  • FileSystemTextStoreTests / S3TextStoreTests: ManifestExists before/after saving, independent of the Text artefact.
  • E2E (BuildAndSearchTests): PUT with no body, with changed services (autocomplete becomes available), replacing sourceData pages, removing an inserted PDF, id mismatch, invalid body, unknown job; a job with image canvases and no text completes with Pdf fulfilled and a PDF link in its text-augmented Manifest.
  • Docs: docs/builder-api.md (PUT section, 400/409 rows, job status names), docs/search-api.md (PDF section and 404 rows), README.md (PDF link condition), CLAUDE.md (PUT endpoint).

@JackLewis-digirati JackLewis-digirati changed the title Allow reprocessing for cover page Modify PUT to allow modification of fields Oct 22, 2026
@JackLewis-digirati
JackLewis-digirati marked this pull request as ready for review October 22, 2026 13:26
@JackLewis-digirati
JackLewis-digirati requested a review from a team as a code owner October 22, 2026 13:26
@JackLewis-digirati
JackLewis-digirati force-pushed the feature/reprocessPdfCoverpage branch from b89a678 to fcc9fce Compare October 23, 2026 11:29
Base automatically changed from feature/pdfCoverpage to main October 23, 2026 15:12
@JackLewis-digirati
JackLewis-digirati merged commit 40ccb73 into main Nov 6, 2026
4 checks passed
@JackLewis-digirati
JackLewis-digirati deleted the feature/reprocessPdfCoverpage branch November 6, 2026 13:12
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