OOXML Processing Limits

GoodMem applies bounded resource policies while extracting text from DOCX, PPTX, and XLSX files and while rendering XLSX worksheets as page images. Deployment operators can replace individual limits at server startup with one versioned JSON value.

This is a process-wide safety policy. It cannot be changed through an ingestion request or an administrative API, and changes take effect only after the server restarts.

Counters are fresh for each library operation. When GoodMem both extracts text and renders page images for one document, each pass receives the same configured ceilings; the two passes do not share one partially consumed budget.

Configuration Precedence

OOXML limits follow GoodMem's standard server configuration precedence:

1. --ooxml-limits-json command-line option
2. GOODMEM_OOXML_LIMITS_JSON environment variable
3. Compiled GoodMem defaults

A blank environment value is treated as unset. A blank command-line value is rejected. The JSON must contain "version": 1; every other field is optional and inherits its compiled default when omitted.

For an installer-managed deployment, put the JSON on one line in the installation profile's .env file, then run goodmem system stop followed by goodmem system start for that profile:

GOODMEM_OOXML_LIMITS_JSON={"version":1,"extraction":{"outputCharacters":33554432}}

New installer-managed profiles include a blank GOODMEM_OOXML_LIMITS_JSON entry and pass it into the server container. When goodmem system upgrade recognizes an older generated profile, it adds the missing .env entry and Compose mapping while preserving an existing value and other Compose customizations. If the CLI cannot safely recognize the generated layout, it warns instead of rewriting it; add the environment mapping manually before setting the value.

The equivalent direct server invocation is:

java -jar goodmem-server.jar \
  --ooxml-limits-json='{"version":1,"extraction":{"outputCharacters":33554432}}'

For a multi-instance deployment, apply the identical resolved policy to every instance and use a rolling restart. During the rollout, instances that have not restarted still enforce the previous policy, so ingestion behavior can differ temporarily. Compare the startup log fingerprint across instances to confirm that they resolved the same policy.

Version 1 Fields and Defaults

All numeric values must be positive integers. Zero never means unlimited.

Text Extraction

textWorkCharacters must be at least outputCharacters. These limits cover the library's instrumented boundaries; they are not a claim that every DOCX or PPTX operation has a comprehensive heap bound. For example, the Apache POI workbook model and every individual decoded object are not all governed by these counters.

XLSX Page-Image Rendering

GoodMem produces one page image per worksheet. A worksheet that exceeds the per-image raster bounds is rendered as a bounded top-left preview. Pictures and charts that cross the preview edge are clipped at their authored scale rather than squeezed into the image.

The current page-image API does not expose whether an XLSX image covers the full worksheet or a bounded preview. Consumers should therefore treat large XLSX page images as previews, even when their metadata looks like an ordinary worksheet image.

Workbook-level limits are hard ceilings. If a workbook exceeds the image-count or aggregate-pixel limit, XLSX page-image processing fails and GoodMem stores no partial set of worksheet images. Text extraction and the rest of memory ingestion are tracked separately and can still complete. A sheet can also fail page-image processing if it exceeds a scene-work ceiling.

XLSX workbook rendering concurrency remains fixed at one and is not configurable through this policy. The width, height, per-image pixel, image-count, and workbook-pixel settings are independent ceilings. It is valid for one stricter setting to make another ceiling unreachable.

Complete Example

{
  "version": 1,
  "extraction": {
    "packageEntries": 10000,
    "zipEntryVisits": 100000,
    "inflatedBytes": 268435456,
    "materializedBytes": 268435456,
    "worksheetVisits": 2048,
    "xmlEvents": 20000000,
    "structuralWorkSteps": 20000000,
    "structuralNestingDepth": 64,
    "rowVisits": 2000000,
    "cellSlotVisits": 10000000,
    "semanticEvents": 500000,
    "outputCharacters": 16777216,
    "textWorkCharacters": 268435456,
    "nestedPayloads": 256,
    "nestingDepth": 6
  },
  "xlsxRendering": {
    "maxWidthPixels": 7680,
    "maxHeightPixels": 4320,
    "maxPixelsPerImage": 33177600,
    "maxVisibleCellSlotsPerSheet": 100000,
    "maxSceneElementsPerSheet": 500000,
    "maxImagesPerWorkbook": 20,
    "maxTotalPixelsPerWorkbook": 663552000
  }
}

GoodMem rejects malformed JSON, duplicate or unknown fields, unsupported versions, non-integral values, numeric overflow, and invalid cross-field combinations before connecting to the database. To roll back an override, remove the command-line option or blank/remove the environment value and restart the server.