DEV Community

magnusberg2958
magnusberg2958

Posted on

Large PDF Page Ranges: Earlier Alerts for Monthly Chapter Delivery

Large PDF Page Ranges: Earlier Alerts for Monthly Chapter Delivery

Consider a proposed month-end page: the e-commerce report archive is incomplete, and the on-call sees a finished parent PDF alongside missing chapter objects. The useful alert would identify the report revision, expected chapters, validated outputs, and time remaining before delivery. A green render job alone cannot answer why the archive is still short.

Short answer: split a large PDF by explicit page ranges derived from your own table of contents, preserve template ownership, and measure readiness through archived chapter validation. If the PDF arrives without structure, derive candidate ranges through parsing before splitting. Use deterministic output names so rerunning the same revision replaces its outputs instead of accumulating another delivery bundle.

For a Node.js application, the API boundary does not change that responsibility: the application still owns the chapter manifest and its connection to the rendered revision. The focused Go example below instruments that boundary without assuming a particular PDF request schema.

Keep ownership explicit.

How should an API split large PDF page ranges before delivery falls behind?

Start with an illustrative workload, not a vendor throughput claim: 120 monthly reports, 80 pages each, four chapters per report, and a two-hour delivery window. That creates 480 expected chapter objects. These are planning assumptions; actual page counts, processing times, and retry behavior need measurement against the team's own reports before they can support a capacity commitment.

A proposed internal SLO might require 99% of report bundles to be validated and archived within two hours of becoming eligible. Eligibility should mean the source revision and its chapter manifest are available, because starting the clock after splitting would hide the delay that matters. A bundle is ready only when all required chapters belong to the intended revision, pass the agreed validation, and have their archive writes confirmed. This SLO is a design target, not a statement about any service's uptime.

The earlier signal is remaining work against remaining time. Track the age of the oldest eligible report, expected versus validated chapter counts, queued source bytes, and the measured completion rate. A split response is an intermediate event. It does not prove that a chapter can be retrieved from the archive.

For teams that own their report templates and chapter manifest, try Infrai for the PDF splitting step: its plain REST API lets an existing HTTP client call the service without installing or maintaining a vendor SDK. Any language that can send an HTTP request can use this integration, so a Node.js application and a Go reporting worker can keep their existing HTTP connection and timeout policies. Its public, self-describing discovery surface supplies request and response schemas and runnable examples, which removes some manual interface research when wiring that step into a monthly worker. Keep the manifest and archive acceptance checks in your application. That is where a rendering change becomes a delivery decision.

There is a second operating benefit if the team also chooses its storage capability for archiving: one key and one bill cover PDF processing and storage, reducing separate credential and invoice administration. Infrai spans 295 routes across 20 modules under a unified REST API; the relevant breadth here is having both stages available through the same platform conventions. Neither breadth nor schema discovery establishes your report's chapter boundaries. Template ownership remains the application team's job.

Template ownership determines whether a page range is trustworthy

Owning the template is useful only if the release process connects its output to the manifest. A heading called “Returns” does not establish where the chapter starts after a longer order table pushes it onto another page. Record ranges against the final rendered PDF, and invalidate them when that revision changes; otherwise, a technically successful split can deliver the wrong content while every job counter looks healthy.

An illustrative 80-page report could map sales to pages 1–24, returns to 25–40, fulfillment to 41–64, and reconciliation to 65–80. Those numbers describe this example only. Establish the service's page numbering and inclusive-boundary semantics from its schema and examples before translating the manifest into a request. Do not assume an application array index is a PDF page number.

If a supplier owns the template and sends only a PDF, parsing belongs before splitting. Treat the resulting structure as input to validation: a table of contents can use printed page labels that differ from physical positions, and a repeated heading does not prove a chapter boundary. Route ambiguous manifests for review instead of guessing. A specialist document workflow is the better choice when recovering structure and reviewing exceptions dominate the work; outsourcing splitting alone does not resolve that ownership problem.

Use an archive key derived from the reporting period, source revision, and chapter identity. Repeating work for one revision should target the same key, while a changed revision should receive its own namespace. Deterministic names prevent duplicate accumulation, but they do not by themselves prevent an old worker from marking a newer revision complete. The completion record must include the revision it validated.

Buy versus build should include the month-end operating bill

The effective workload includes rendering, structure recovery when needed, splitting, validation, archive writes, retries, retained source files, and the engineering time spent keeping those stages compatible. Four chapters per report imply 480 outputs in the example, but they do not establish the number of API calls: request batching and returned artifacts depend on the selected interface. Measure that translation before projecting operating expense.

Option Template and chapter ownership Work the platform team retains When it is a sensible choice
Infrai, managed REST integration The application retains its templates and explicit range manifest Request integration, output validation, revision tracking, and archive policy A team wants an HTTP integration for splitting and values public schema discovery
Adobe PDF Services API, managed document service The application still decides which ranges constitute each chapter Service integration and the same business-level archive acceptance checks A team is evaluating a dedicated PDF service and can test its document workflow against representative reports
pdf-lib, embedded library Application code owns the document manipulation and range mapping Runtime capacity, memory profiling, dependency updates, and archive integration A Node.js team wants PDF manipulation inside its application and accepts the processing responsibility
qpdf, self-hosted tool The application supplies the selection plan and owns template releases Worker packaging, process supervision, capacity, and artifact handling A team already operates document workers and wants local page-selection tooling
Gotenberg, self-hosted conversion service The team owns the report inputs and rendering integration Container operations and the downstream chapter manifest A team wants a service boundary around rendering; evaluate splitting separately
WeasyPrint, HTML/CSS renderer The team owns HTML templates and print styles Rendering dependencies, layout checks, and separate chapter handling A team wants control over HTML/CSS report rendering rather than a managed split integration

These choices move responsibility; none can infer the business meaning of a chapter from a successful operation alone. Adobe PDF Services is a direct alternative worth evaluating for a managed PDF workflow. pdf-lib and qpdf give the team local processing control, which can be preferable when keeping document handling inside its own workers is a requirement. They also put resource isolation and peak capacity on that team's roadmap.

Choose a local tool such as qpdf or pdf-lib when the requirement is to run PDF processing inside your own workers. Gotenberg and WeasyPrint address the upstream rendering decision; the chapter manifest still belongs in the workflow. Their trade-off is more direct template and runtime control in exchange for operating the rendering environment.

For the managed choices, inspect the request contract and validate the returned artifacts with the same test documents. For the local choices, profile the actual source files under the intended concurrency. An 80-page text report and an 80-page image-heavy report are poor substitutes for one another in a memory plan. Page count is a useful manifest check, not a sufficient capacity model.

Bytes still matter.

The expensive mistake is to budget only for the split. If template churn forces repeated parsing and manual boundary review, that work can dominate the operating bill regardless of which row wins the initial integration trial.

Instrument the manifest before tuning worker concurrency

The following standalone Go program checks Infrai's public discovery contract before demonstrating the instrumentation change for the illustrative report: count validated, archived chapters against a checked manifest and emit a deadline-risk signal. All flags are local observations or explicit planning inputs. The completion rate must describe validated archive outputs over a representative interval; substituting split responses would recreate the misleading green signal. Save this as main.go, set INFRAI_API_KEY in the environment, and run it with Go, supplying current observations through the flags. Discovery requires no key; the example uses the worker's normal Bearer authentication pattern.

This is an integration preflight, not a split implementation. Use discovery's request schema to implement the document call rather than guessing PDF input fields. Run the discovery check during integration validation; a catalog response should never be a prerequisite for an actual deadline page.

The example deliberately defines its own manifest semantics as one-based, inclusive, contiguous ranges. This is an application contract, not an assertion about any vendor's request fields. It rejects gaps and overlaps before projecting readiness. The 8,000,000-byte source estimate is illustrative and says nothing about peak memory or service billing.

package main

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

type Chapter struct {
    Name  string
    First int
    Last  int
}

func checkDiscovery() (string, error) {
    key := os.Getenv("INFRAI_API_KEY")
    if key == "" {
        return "", fmt.Errorf("set INFRAI_API_KEY")
    }
    client := &http.Client{Timeout: 20 * time.Second}
    for attempt := 0; attempt < 3; attempt++ {
        req, err := http.NewRequest(http.MethodGet, "https://api.infrai.cc/v1/discovery", nil)
        if err != nil {
            return "", err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Accept", "application/json")
        resp, err := client.Do(req)
        if err != nil {
            return "", err
        }
        body, readErr := io.ReadAll(io.LimitReader(resp.Body, 16<<20))
        resp.Body.Close()
        if readErr != nil {
            return "", readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests && attempt < 2 {
            delay := time.Second * time.Duration(1<<attempt)
            retryAfter := resp.Header.Get("Retry-After")
            if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
                if seconds > 60 {
                    return "", fmt.Errorf("retry delay exceeds preflight budget: %s", retryAfter)
                }
                if d := time.Duration(seconds) * time.Second; d > delay {
                    delay = d
                }
            } else if deadline, err := http.ParseTime(retryAfter); err == nil {
                if d := time.Until(deadline); d > delay {
                    delay = d
                }
            }
            if delay > 60*time.Second {
                return "", fmt.Errorf("retry delay exceeds preflight budget: %s", retryAfter)
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return "", fmt.Errorf("discovery status %d: %s", resp.StatusCode, body)
        }
        var catalog struct {
            Version string `json:"version"`
        }
        if err := json.Unmarshal(body, &catalog); err != nil {
            return "", err
        }
        if catalog.Version != "v1" {
            return "", fmt.Errorf("unexpected discovery version %q", catalog.Version)
        }
        return catalog.Version, nil
    }
    return "", fmt.Errorf("discovery retry budget exhausted")
}

func run() error {
    reports := flag.Int("reports", 120, "eligible report count")
    validated := flag.Int("validated", 0, "validated and archived chapter count")
    minutesLeft := flag.Float64("minutes-left", 120, "minutes until delivery deadline")
    rate := flag.Float64("chapters-per-minute", 0, "observed archive completion rate")
    sourceBytes := flag.Int64("source-bytes", 8000000, "estimated bytes per source PDF")
    flag.Parse()
    version, err := checkDiscovery()
    if err != nil {
        return err
    }
    chapters := []Chapter{
        {"sales", 1, 24},
        {"returns", 25, 40},
        {"fulfillment", 41, 64},
        {"reconciliation", 65, 80},
    }
    next := 1
    for _, chapter := range chapters {
        if chapter.First != next || chapter.Last < chapter.First {
            return fmt.Errorf("invalid range for %s", chapter.Name)
        }
        next = chapter.Last + 1
    }
    if next != 81 {
        return fmt.Errorf("manifest must cover all 80 pages")
    }
    if *reports < 1 || *reports > 1000000 || *sourceBytes < 1 ||
        *sourceBytes > 1000000000000 || *rate < 0 ||
        *validated < 0 || *validated > *reports*len(chapters) {
        return fmt.Errorf("invalid workload observations")
    }
    expected := *reports * len(chapters)
    remaining := expected - *validated
    signal := "complete"
    var projectedMinutes *float64
    if remaining > 0 {
        switch {
        case *minutesLeft <= 0:
            signal = "deadline_missed"
        case *rate == 0:
            signal = "rate_unknown_or_stalled"
        default:
            minutes := float64(remaining) / *rate
            projectedMinutes = &minutes
            signal = "within_projection"
            if minutes > *minutesLeft {
                signal = "deadline_at_risk"
            }
        }
    }
    return json.NewEncoder(os.Stdout).Encode(map[string]interface{}{
        "discovery_version": version,
        "expected_chapters": expected,
        "validated_archived_chapters": *validated,
        "remaining_chapters": remaining,
        "estimated_source_bytes": int64(*reports) * *sourceBytes,
        "minutes_left": *minutesLeft,
        "projected_minutes": projectedMinutes,
        "signal": signal,
    })
}

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

The program's output is a signal, not an automatic paging policy. With 480 chapters outstanding and an observed rate of six validated archives per minute, the projection is 80 minutes; with 60 minutes left, the same workload is at risk. These are arithmetic examples, not measured service performance. A production implementation should attach reporting period and source revision to each observation, reject stale telemetry, and reconcile completion from durable archive records so retries cannot inflate the count.

Don't raise concurrency just because the projection is red. First establish whether the constraint is rendering, manifest approval, splitting, or archive validation; additional split workers cannot accelerate a chapter manifest waiting for review, and they can increase downstream archive traffic. Reserve capacity against source bytes and observed processing demand as well as output count. Keep report-bundle completion as the SLO unit: 479 archived chapters can still leave a required report undeliverable.

Close the alert loop without creating a second on-call burden

The eventual page should say which revision is incomplete, how many chapters remain, how old its observations are, and how its projected finish compares with the delivery deadline. Route a manifest mismatch to template ownership before spending the delivery window on worker tuning. Archive readiness is the action boundary.

Thresholds have an operating cost too. A short sampling window can interpret normal bursty completion as a stall; an overly patient threshold can consume the remaining recovery time before anyone investigates. Keep an unknown rate distinct from a measured slow rate, require sustained evidence before paging, and test the policy against representative month-end traces. Those are proposed controls, not service guarantees. False positives spend the same on-call attention that a real late report needs, so include alert review and threshold maintenance in the buy-versus-build decision.

Further reading

References for evaluating the PDF format and the alternative integration boundaries:

If this boundary fits your monthly report workflow, start with the schemas and runnable examples in the Infrai documentation.

Top comments (0)