Proxy Caching, Negative Cache, Remote Storage, Routing Rules, Repository Health, and Failure Behavior: Concepts, Architecture, and Mental Model

1. The practical problem: a proxy can be “working” and still serve the wrong operational answer

A developer asks for a package and Nexus returns something quickly. That single observation does not tell an operator whether Nexus served a local cached asset, checked the remote, reused cached metadata, honored a negative-cache entry, refused the path because of a routing rule, skipped the remote because the repository is blocked, or failed because DNS, TLS, an outbound HTTP proxy, upstream credentials, rate limits, or the upstream service itself failed.

The operational skill is therefore not “know where the proxy checkbox is.” It is to build a causal chain from request → local state → policy → outbound attempt (or deliberate non-attempt) → response, and to collect evidence at each boundary.

2. Positive cache: miss, fill, hit, revalidation

flowchart TD
C[Client request] --> N{Local Nexus cache?}
N -->|No| P{Routing / blocked policy allows remote?}
P -->|No| X[Return controlled failure]
P -->|Yes| U[Request remote upstream]
U -->|Found| B[Store blob + metadata]
B --> R[Return component]
N -->|Yes| A{Age still valid?}
A -->|Yes| R
A -->|No| U
U -->|Not found| G[Store negative-cache result]
G --> F[Return not found]

On the first successful request, a proxy repository has no local component to serve. It asks the remote, stores the returned content in its blob store and the associated repository/component/asset state in Nexus metadata, then returns the response. Later requests can be served locally until cache-age policy requires another remote check.

Maximum Component Age controls how long a cached component can be considered current before Nexus checks the remote for a modified copy. Maximum Metadata Age controls remote refresh of metadata such as package indexes or version lists. Sonatype documents a default of 1440 minutes (24 hours) for both common proxy age fields. For component metadata, Nexus honors the greater of the component and metadata age values before rechecking.

3. Negative cache is cached absence, not missing blob content

Public repositories often answer 404 Not Found for a coordinate that does not exist. Repeating the same impossible request every few seconds wastes outbound capacity and can contribute to upstream throttling. Nexus therefore stores a temporary “not found” decision. The default Not Found Cache TTL is 1440 minutes.

4. Blocked versus Auto Blocking

Blocked is an explicit operator state on a proxy repository: Nexus stops sending outbound requests to that remote. Cached components remain available. Auto Blocking is a resilience mechanism: when enabled, Nexus can automatically block an unavailable remote, periodically retest it, and remove the block after recovery.

stateDiagram-v2
[*] --> Reachable
Reachable --> AutoBlocked: repeated remote failure
AutoBlocked --> AutoBlocked: serve local cache / periodic retest
AutoBlocked --> Reachable: remote retest succeeds
Reachable --> ManuallyBlocked: operator checks Blocked
ManuallyBlocked --> Reachable: operator clears Blocked

Blocking a proxy is therefore an excellent disposable failure simulator: it prevents outbound traffic without changing DNS, firewalls, public upstream services, or operating-system routes. It also demonstrates the availability value of previously cached content.

5. Routing rules constrain outbound namespace reach

A Nexus routing rule is attached to a proxy repository. It is not a group-member routing rule and it does not reorder group members. A BLOCK rule denies matching request paths; an ALLOW rule permits matching paths. Matchers use Java-compatible regular expressions. Only one routing rule can be assigned to a given proxy, though one rule can be reused by multiple proxies.

Routing rules are useful for egress governance and namespace-confusion defenses: for example, an organization can prevent an internal namespace from ever being requested from a public upstream. The UI includes a rule tester; use it before assignment. Keep expressions simple because expensive regular expressions can become a performance or denial-of-service problem.

6. Remote storage is a dependency chain, not just a URL

These layers explain why “I can curl the upstream from my laptop” is weak evidence. Nexus performs the remote request from the Nexus runtime environment, through its DNS, truststore, egress proxy and network path.

7. Repository Health Check is not the same as remote health

Repository Health Check (RHC) analyzes open-source risk for supported proxy formats such as Maven, npm, NuGet, PyPI, RubyGems and Yum. It can show Community users a summary of vulnerabilities and license warnings; the detailed report is Pro-only. RHC also calls Sonatype data services and can itself encounter outbound certificate/proxy problems.

By contrast, auto-blocking remote health answers a simpler availability question: can this proxy reach its configured remote? Do not use an RHC vulnerability summary to prove that an upstream is reachable, and do not use an auto-block state to make a vulnerability judgment.

8. Read-only inspection before changing anything

export NX_URL="http://127.0.0.1:8081"
export LAB="${TMPDIR:-/tmp}/nexus-ch13-inspect"
rm -rf "$LAB" && mkdir -p "$LAB"

curl -fsS "$NX_URL/service/rest/v1/status"   | tee "$LAB/status.txt"
curl -fsS "$NX_URL/service/rest/v1/repositories"   | tee "$LAB/repositories.json"
curl -fsS "$NX_URL/service/rest/swagger.json"   > "$LAB/swagger.json"

grep -o '/v1/routing-rules[^" ]*' "$LAB/swagger.json"   | sort -u | head -n 20 || true

On an authenticated-only instance, repeat the same read-only calls using a disposable least-privilege account and a protected netrc file as shown in Lesson 2. Also inspect Settings → Repository → Repositories for the proxy's Remote storage, cache ages, negative cache, Blocked/Auto Blocking and routing-rule assignment before editing.

9. DevOps connection: proxy policy is delivery policy

A long cache age improves resilience and reduces upstream load but delays freshness. A short negative TTL sees newly published versions sooner but generates more remote traffic. A broad public proxy is convenient but increases namespace exposure. Aggressive retries can amplify an upstream incident. The repository operator owns these tradeoffs because they directly determine CI repeatability, developer latency and software-supply-chain egress.

10. Knowledge check

11. Summary and next step

You now have the state model needed for the chapter: positive content cache, negative cache, age-based revalidation, routing constraints, manual/automatic blocking, remote transport dependencies and RHC as a separate risk-analysis feature. Lesson 2 turns that model into measured before/after evidence.

Official references and version notes

• Sonatype: Repository Types.
• Sonatype: Configurable Repository Fields — proxy cache ages, negative cache, blocked and auto-blocking fields.
• Sonatype: Repository Actions — Invalidate Cache, Rebuild Index and HealthCheck actions.
• Sonatype: Routing Rules.
• Sonatype: HTTP Request and Proxy Settings.
• Sonatype: Repository Health Check and Self-Hosted Feature Matrix.
• Sonatype: Securing Nexus Repository — current private-network/SSRF controls for remote URLs.
• Sonatype: Nexus Repository API Reference.
• Sonatype verified Nexus Docker image tags.

Version-sensitive statements were rechecked on 2026-08-26. Sonatype's verified container registry exposes Nexus Repository 3.95.2 as the current latest image line, while the archive-download documentation may lag at 3.94.1. This chapter therefore records the actual running server version as authoritative evidence and uses 3.95.2 only as the concrete current reference baseline. The mandatory work requires Community-compatible proxy repositories, routing rules, cache controls and the Repository Health Check summary only; no Pro-only detailed RHC report, staging, HA, user tokens, export/import or Repository Firewall capability is required.