feat: Add memory usage test framework

.gitignore

@@ -122,3 +122,7 @@ target/
 src/c2pa/libs/
 !tests/fixtures/*.pem
 !tests/fixtures/*.key
+
+# Memory profiling reports
+tests/perf/reports/*.html
+tests/perf/reports/*.bin

Makefile

@@ -110,3 +110,23 @@ download-native-artifacts:
 # Build API documentation with Sphinx
 docs:
 	python3 scripts/generate_api_docs.py
+
+# Memory profiling with memray (runs in Docker, reports go to tests/perf/reports/)
+# More details for usage are in tests/perf/README.md
+PERF_ENV ?= python-3.12-slim
+MEMRAY_ITERATIONS ?= 100
+MEMRAY_THRESHOLD ?= 1.1
+SCENARIO ?=
+SCENARIO_ARG := $(if $(SCENARIO),--scenario $(SCENARIO),)
+.PHONY: memory-use-bench
+memory-use-bench:
+	docker build -f tests/perf/Dockerfiles/$(PERF_ENV)-perf-Dockerfile -t c2pa-memray-$(PERF_ENV) .
+	docker run --rm -v $(PWD):/workspace -e PYTHONPATH=/workspace/src -e PERF_ENV=$(PERF_ENV) -e MEMRAY_ITERATIONS=$(MEMRAY_ITERATIONS) -e MEMRAY_THRESHOLD=$(MEMRAY_THRESHOLD) c2pa-memray-$(PERF_ENV) python -m tests.perf.run_profile $(SCENARIO_ARG) $(PERF_ARGS)
+	@echo ""
+	@echo "Reports written to tests/perf/reports/"
+	@echo "Open tests/perf/reports/<scenario>-{peak,leaks,temporary}.html in a browser"
+
+.PHONY: clean-memory-perf-reports
+clean-memory-perf-reports:
+	rm -f tests/perf/reports/*.html tests/perf/reports/*.bin
+	@echo "Cleared tests/perf/reports/"

tests/perf/Dockerfiles/python-3.10-slim-perf-Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.10.20-slim-bookworm
+
+WORKDIR /workspace
+
+# libunwind for memray native stack unwinding
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libunwind-dev \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pre-install Python deps using only the requirements files (layer-cached).
+# The full project arrives via the -v mount at runtime.
+COPY requirements.txt requirements-dev.txt ./
+RUN pip install --no-cache-dir -r requirements.txt -r requirements-dev.txt
+
+RUN pip install --no-cache-dir memray==1.19.3
+
+COPY tests/perf/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["python", "-m", "tests.perf.run_profile"]

tests/perf/Dockerfiles/python-3.12-slim-perf-Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12.13-slim-bookworm
+
+WORKDIR /workspace
+
+# libunwind for memray native stack unwinding
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libunwind-dev \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pre-install Python deps using only the requirements files (layer-cached).
+# The full project arrives via the -v mount at runtime.
+COPY requirements.txt requirements-dev.txt ./
+RUN pip install --no-cache-dir -r requirements.txt -r requirements-dev.txt
+
+RUN pip install --no-cache-dir memray==1.19.3
+
+COPY tests/perf/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["python", "-m", "tests.perf.run_profile"]

tests/perf/Dockerfiles/ubuntu-22.04-perf-Dockerfile

@@ -0,0 +1,31 @@
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+WORKDIR /workspace
+
+# Ubuntu 22.04 ships Python 3.10 as python3 by default.
+# libunwind for memray native stack unwinding.
+# python3-dbg supplies the interpreter's debug symbols so memray can resolve
+# file names + line numbers for native (C) frames in the flamegraphs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    python3-venv \
+    python3-dbg \
+    libunwind-dev \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -s /usr/bin/python3 /usr/bin/python
+
+# Pre-install runtime deps only. Project arrives via -v mount.
+COPY requirements.txt ./
+RUN pip3 install --no-cache-dir -r requirements.txt
+
+RUN pip3 install --no-cache-dir memray==1.19.3 requests==2.34.2
+
+COPY tests/perf/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["python", "-m", "tests.perf.run_profile"]

tests/perf/Dockerfiles/ubuntu-24.04-perf-Dockerfile

@@ -0,0 +1,31 @@
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+WORKDIR /workspace
+
+# Ubuntu 24.04 ships Python 3.12 as python3 by default.
+# libunwind used for memray native stack unwinding.
+# python3-dbg supplies the interpreter's debug symbols so memray can resolve
+# file names + line numbers for native (C) frames in the flamegraphs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    python3-venv \
+    python3-dbg \
+    libunwind-dev \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -s /usr/bin/python3 /usr/bin/python
+
+# Pre-install runtime deps only. Project arrives via -v mount.
+COPY requirements.txt ./
+RUN pip3 install --no-cache-dir --break-system-packages -r requirements.txt
+
+RUN pip3 install --no-cache-dir --break-system-packages memray==1.19.3 requests==2.34.2
+
+COPY tests/perf/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["python", "-m", "tests.perf.run_profile"]