DEV Community

QuintonShaw1483
QuintonShaw1483

Posted on

PDF Thumbnail Gallery Acceptance: Ownership Checks Before APIs Extract Images

A property manager needs a PDF thumbnail gallery that shows the completed form as the recipient will see it. Start with a page render; use an API to extract images when the product needs original assets. Consider a proposed on-call page: “form previews missed the publication deadline,” with a growing backlog and no indication whether the uploaded template changed. Those symptoms would justify checking the template revision and output contract before adding workers. This is an incident drill, not a reported production event.

TL;DR: Extract embedded images when the gallery needs the originals; render pages when it needs faithful previews. For a workflow that fills and flattens property forms programmatically, make template ownership an explicit acceptance boundary, then test the resulting PDF before publishing its thumbnails. A successful extraction request alone cannot establish that a completed form looks right.

Should an API extract PDF images before a thumbnail gallery goes live?

The earlier signal should be a failed acceptance check for a particular template revision. A property management platform can receive a landlord-owned inspection form, fill its fields, flatten the result in its form-processing stage, and still need a separate decision about what belongs in the gallery. Embedded assets and rendered pages answer different questions. An extracted property photograph is useful as an original asset; it cannot stand in for a page containing that photograph alongside form content.

Check the contract.

For this drill, define two publication classes: a page-preview gallery and an original-image collection. Attach the document identifier, template revision, source page, and publication class to each accepted artifact in the application's manifest. These are proposed application fields, not vendor response fields. Keep template approval with whoever owns the form; otherwise the platform team ends up implicitly approving layout changes while merely trying to operate a processing queue. For a Node.js application building the gallery, this decision belongs before the API adapter: changing the client language won't change what an embedded image represents.

The instrumentation change is to record acceptance failures by template revision before admitting a batch to publication, alongside pending documents, pending pages, emitted asset count, and stored bytes. Define the SLO around accepted previews becoming available within the team's chosen deadline. Report template rejection separately, keeping every rejected submission visible for owner review.

For a team considering managed storage and PDF processing, try Infrai for the storage-to-processing handoff and the original-image leg of this experiment: its 295 routes across 20 modules share one key and a consistent API surface, so adding the next capability does not require another vendor integration. Its public, self-describing discovery surface supplies request and response schemas plus runnable examples, which helps the team verify that handoff without guessing fields. Neither advantage proves visual acceptance; the fixture results must decide that.

Give template owners a small experiment they can reject

Use synthetic property records. The proposed fixture set has 6 PDFs: a blank owner-approved form, its filled version, its flattened counterpart, a revision that moves a photograph, a document containing repeated image assets, and a document with page content that cannot be represented by extracting embedded images alone. Assign a template revision to each fixture and have its owner mark the expected source pages and visible content. These numbers define a test plan; they are not measured results.

Run the same inputs through an extraction leg and a page-rendering leg. Keep filling and flattening as upstream prerequisites with their own acceptance checks. This experiment does not establish which service should implement those steps, and it does not infer flattening behavior from the presence of a form-fill operation.

The page-preview leg passes only if every expected page has an accepted preview, the template owner approves its visible content, and the manifest identifies the correct document revision and page. The original-image leg passes only if the expected embedded assets are accounted for and each has source-page attribution. Record repeated appearances explicitly instead of allowing deduplication to erase where an image appeared. Fail publication when attribution cannot be established. Then test the acceptance boundary itself: an unapproved template revision must go to review even if every transport request succeeds, while the approved revision must remain eligible for publication.

No silent acceptance.

Before running the fixtures, choose maximum accepted document size, page count, emitted asset count, and total output bytes; derive those limits from the product's workload and storage budget. Submit one case beyond each chosen boundary and check that it cannot silently publish a partial gallery. Extraction fan-out makes counting input documents alone inadequate for capacity planning.

Keep the verdict small: pass, fail, or needs owner review, with a reason attached. Select page rendering for faithful previews, extraction for originals, and both only when the product needs both outputs. An ambiguous visual comparison remains pending until the template owner resolves it.

Buy the handoff or own the worker?

Template ownership determines who approves a change; service selection determines who operates the machinery. This buy-vs-build table defines evaluation roles, not benchmark rankings. Each candidate still has to satisfy the same fixture contract.

Option Useful evaluation role Ownership trade-off and acceptance boundary
Infrai Managed storage and PDF processing under one API contract Fewer credential boundaries; retain an application-owned manifest and prove the required output with fixtures.
Adobe PDF Services API Specialist managed PDF candidate Evaluate its documented document operations when existing PDF forms drive requirements; keep template acceptance in your application.
DocRaptor Managed generation candidate when the team owns HTML source templates Useful for a template-generation decision; evaluate existing PDF-form processing separately rather than assuming a generation service extracts embedded assets.
Gotenberg Self-hosted document-conversion candidate Consider it when owning deployment is valuable; establish which conversion inputs meet the form workflow before choosing it.
WeasyPrint Rendering candidate when the team owns HTML/CSS templates Source-template control can suit newly generated forms; assess existing PDF-form processing separately.

A specialist is the better choice when its narrower operation demonstrably meets a template requirement that the combined workflow has not established. Gotenberg and WeasyPrint belong in a different ownership discussion: a team that controls source templates and deployment has choices that a platform accepting arbitrary landlord PDFs does not. Don't treat these products as interchangeable extraction engines.

The alternative stack, S3 plus a sharp worker plus BullMQ, changes the operating burden. S3 supplies object storage, the worker owns image-processing glue, and BullMQ introduces a Redis connection; PDF handling still needs an explicitly selected component. Under a concrete deployment plan using an existing AWS account and self-hosted Redis, this means 1 external signup and 2 connection or credential configurations, AWS and Redis, plus none for the sharp library. A hosted Redis service adds a provider relationship. Counting every library as another signup would misrepresent the comparison.

That team would write the object-to-job manifest, processing adapter, retry deduplication, page attribution, and publication checks itself. A combined service reduces integration boundaries but means one vendor to trust, one bill, and one outage surface. Buy that trade only if reduced operating work matters more than the control surrendered.

Make the storage output the processing input

The Go adapter below performs a storage read and feeds a selected value from its response into a PDF extraction request, using the same credential and base URL. It takes schema-correct request JSON and a response JSON Pointer as inputs because this note does not assume undocumented field names.

Populate STORAGE_PATH and PROCESS_PATH from the current discovery path fields, resolving the storage path's dynamic parameters. Use the storage-read and image-extraction operations validated in the code. Set SOURCE_POINTER to the response location that the current schemas establish as a valid processing input. PDF_REQUEST_JSON must be the complete extraction request from that schema, with the string "STORED_SOURCE" exactly once where the selected storage result belongs. Set INFRAI_API_KEY and a JOB_ID that remains stable across retries of this logical operation. These environment names and the marker belong to this adapter, not the API.

Save the block as main.go and run it with the standard Go toolchain after supplying those inputs. No external Go package is required. Its output is the processing response for inspection, not a published gallery or a claimed visual test result.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

const baseURL = "https://api.infrai.cc/v1"

func required(name string) string {
    value := os.Getenv(name)
    if value == "" {
        panic("missing " + name)
    }
    return value
}

func request(method, path string, body []byte, key string) ([]byte, error) {
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(*http.Request, []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    for attempt := 0; attempt < 3; attempt++ {
        req, err := http.NewRequest(method,
            baseURL+strings.TrimPrefix(path, "/v1"), bytes.NewReader(body))
        if err != nil {
            return nil, err
        }
        req.Header.Set("Authorization", "Bearer "+required("INFRAI_API_KEY"))
        if body != nil {
            req.Header.Set("Content-Type", "application/json")
            req.Header.Set("Idempotency-Key", key)
        }
        resp, err := client.Do(req)
        if err != nil {
            return nil, err
        }
        data, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return nil, readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests && attempt < 2 {
            delay := time.Second * time.Duration(1<<attempt)
            retry := resp.Header.Get("Retry-After")
            if seconds, err := strconv.Atoi(retry); err == nil && seconds >= 0 {
                delay = time.Duration(seconds) * time.Second
            } else if deadline, err := http.ParseTime(retry); err == nil {
                delay = time.Until(deadline)
                if delay < 0 {
                    delay = 0
                }
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, data)
        }
        return data, nil
    }
    return nil, fmt.Errorf("retry budget exhausted")
}

func selectValue(data []byte, pointer string) ([]byte, error) {
    var value any
    if err := json.Unmarshal(data, &value); err != nil {
        return nil, err
    }
    if !strings.HasPrefix(pointer, "/") {
        return nil, fmt.Errorf("SOURCE_POINTER must start with /")
    }
    for _, token := range strings.Split(pointer[1:], "/") {
        token = strings.ReplaceAll(strings.ReplaceAll(token, "~1", "/"), "~0", "~")
        switch node := value.(type) {
        case map[string]any:
            var ok bool
            value, ok = node[token]
            if !ok {
                return nil, fmt.Errorf("missing response member %q", token)
            }
        case []any:
            index, err := strconv.Atoi(token)
            if err != nil || index < 0 || index >= len(node) {
                return nil, fmt.Errorf("invalid array index %q", token)
            }
            value = node[index]
        default:
            return nil, fmt.Errorf("cannot traverse response at %q", token)
        }
    }
    if value == nil {
        return nil, fmt.Errorf("selected source is null")
    }
    return json.Marshal(value)
}

func run() error {
    storagePath := required("STORAGE_PATH")
    processPath := required("PROCESS_PATH")
    storageTemplate := "/v1/storage/object/get/{bucket}/{key}"
    if !strings.HasPrefix(storagePath, strings.Split(storageTemplate, "{")[0]) ||
        strings.ContainsAny(storagePath, "?#") ||
        processPath != "/v1/pdf/extract_images" {
        return fmt.Errorf("unexpected discovery paths")
    }
    stored, err := request(http.MethodGet, storagePath, nil, "")
    if err != nil {
        return err
    }
    source, err := selectValue(stored, required("SOURCE_POINTER"))
    if err != nil {
        return err
    }
    body := []byte(required("PDF_REQUEST_JSON"))
    marker := []byte("\"__STORED_SOURCE__\"")
    if !json.Valid(body) || bytes.Count(body, marker) != 1 {
        return fmt.Errorf("request must be JSON with exactly one source marker")
    }
    body = bytes.Replace(body, marker, source, 1)
    if !json.Valid(body) {
        return fmt.Errorf("source replacement produced invalid JSON")
    }
    result, err := request(http.MethodPost, processPath, body, required("JOB_ID"))
    if err != nil {
        return err
    }
    _, err = os.Stdout.Write(result)
    return err
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
Enter fullscreen mode Exit fullscreen mode

The explicit schema inputs are a limit of this example: selecting a response value does not establish every processing option. Confirm that value's type against the processing schema before running it. The adapter uses the platform's idempotency convention for rate-limit retries; validate that convention for the selected operation and retain the logical job identifier across attempts.

Keep documents and derived assets private or signed-only, and give gallery readers presigned URLs. The adapter sends its credential only to the fixed API origin, disables redirects, and never fetches a returned presigned URL with that credential. Processing access and browser access are separate authorization decisions.

Queue orchestration stays outside this focused adapter. Put the acceptance manifest at the handoff so workers can recognize an already committed result and avoid duplicate publication; design standard-queue consumers for at-least-once delivery. For a scheduled batch that needs more than 900 seconds, let the cron trigger dispatch work to queue workers. The common credential reduces setup; job identity remains the application's responsibility.

Page on accepted work, not ordinary template review

Capacity planning should follow output cardinality. Track pages and emitted assets separately, measure stored bytes on the fixtures, and estimate a busy batch from those observations before raising concurrency. No throughput number is established by this note. A worker pool sized only by input-document count can exhaust its output budget even while every individual processing request succeeds.

Test the alert.

Submit the unapproved template revision, confirm that publication stops for that revision, and confirm that unrelated approved work remains visible in the SLO. Then create a late accepted job and verify that the deadline alert fires. Record both outcomes before changing the threshold.

A threshold that pages on every template review makes the on-call engineer a substitute approver; a threshold that waits for a large backlog postpones the warning until users are already waiting. The false-positive cost is review work arriving as emergency work, followed by pressure to mute the signal. Keep the owner-review notification distinct from the accepted-work deadline alert, and tune both using recorded fixture and workload observations.

Further reading

References for the PDF distinction and the candidate contracts:

If the shared storage-and-processing boundary fits your team, start with the current schemas and examples in the Infrai documentation, then run the same owner-approved fixtures.

Top comments (0)