Hosted, Proxy, and Group Repositories: Design Patterns, Routing, Caching, and Promotion Flows: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: preserve evidence before changing state

Routing incidents become expensive when operators “fix” three layers at once. Preserve a concise request/response first, then walk from the client inward:

1. Confirm Nexus version, edition and Java/runtime baseline.
2. Record the exact client URL, method and authentication mode.
3. Inspect repository type, group membership/order and proxy remote/routing rules.
4. Inspect authorization for the path actually requested.
5. Inspect component, asset and metadata state in the relevant member repository.
6. If a proxy is involved, inspect cached state, negative cache and upstream health.
7. Inspect database/blob/disk health only after routing/content evidence points there.
8. Inspect logs, tasks and metrics around the controlled request.
9. Apply the least destructive correction and repeat the same controlled request.

This sequence prevents a routing error from becoming an unnecessary cache purge, privilege broadening or storage surgery.

2. Intentionally broken example: upload to the read group

Use the disposable Lesson 2 topology. The following request deliberately targets the group. Preserve the HTTP status/body; do not hide the failure by immediately switching URLs.

# POSIX/Bash. Windows PowerShell guidance follows this block.
LAB="$HOME/nexus-ch04-lab"
NX_URL="http://127.0.0.1:8081"
mkdir -p "$LAB/evidence" "$LAB/payload" "$LAB/promote"
umask 077
read -rsp "Disposable Nexus admin password: " NX_PASS; printf "\n"
printf 'machine 127.0.0.1 login admin password %s\n' "$NX_PASS" > "$LAB/nexus.netrc"
unset NX_PASS
NETRC="$LAB/nexus.netrc"

# Never print, commit, or reuse this temporary credential file.

# Reuse a harmless local JAR/POM only if the Lesson 2 disposable topology exists.
# This request is intentionally wrong: a group is not a publication target.
curl --silent --show-error --netrc-file "$NETRC"   -X POST "$NX_URL/service/rest/v1/components?repository=academy-ch04-dev-read"   -F "maven2.groupId=com.example.academy"   -F "maven2.artifactId=wrong-target-demo"   -F "maven2.version=0.0.1"   -F "maven2.asset1=@$LAB/payload/promotion-demo-1.0.0.jar"   -F "maven2.asset1.extension=jar"   -F "maven2.asset2=@$LAB/payload/promotion-demo-1.0.0.pom"   -F "maven2.asset2.extension=pom"   -o "$LAB/evidence/20-wrong-target-body.txt"   -w "%{http_code}\n"   | tee "$LAB/evidence/20-wrong-target-status.txt"

The exact error body may vary by pinned version and request validation, but the topology conclusion does not: you chose a read aggregator rather than a hosted write target. The repair is to correct the publisher endpoint, not to grant broader privileges or manipulate repository internals.

3. Member-order shadowing: prove it with synthetic bytes

To demonstrate shadowing safely, use only the two disposable hosted repositories. Publish the same synthetic Maven path to both with intentionally different JAR bytes, then create or temporarily use a disposable group whose order you control. Do not use a real package name.

If group order is dev → release, the group should return the dev bytes; if release → dev, it should return the release bytes. Use direct curl retrieval so Maven’s local repository cannot mask the group behavior. The repair is to restore the documented group order and, for owned namespaces, add appropriate routing governance.

4. Proxy upstream outage: cached versus uncached

Do not unplug networks or attack public services. On the disposable academy-ch04-central proxy, use the supported Blocked repository control to simulate no remote requests. First make sure one artifact is already cached. Then block the proxy and request that cached path through the group: cached content can still be served. Request a never-cached public path: Nexus cannot obtain it from the blocked remote.

Restore the proxy immediately after the exercise and capture the configuration before/after. This demonstrates the availability value of a proxy cache without confusing it with full offline mirroring.

5. Negative cache: the “it exists now but Nexus still says 404” case

A proxy can remember a remote not-found response. If the upstream later publishes that coordinate before the negative-cache TTL expires, Nexus may continue to answer from the cached miss. Inspect the negative-cache settings and request history first. If the situation is confirmed and you need immediate re-evaluation, use the supported Invalidate Cache repository action.

6. Accidental public fallback for internal namespaces

A group whose last member is Maven Central can query the public proxy when earlier members miss. That is correct for public dependencies but dangerous for an internally owned namespace if no internal component exists yet. A typo or absent internal version could fall through to public upstream.

Repair this at the policy layer: authoritative internal members first, routing rules that prevent the internal namespace from being requested from the public remote, and client/network configuration that does not silently bypass Nexus. Do not “fix” the symptom by disabling verification or adding arbitrary public repositories.

7. Rebuild-style promotion: a silent identity failure

This failure may return HTTP 200 and still be wrong. If a release job recompiles source rather than moving/copying the accepted candidate, the release checksum may differ. Preserve the candidate checksum, release checksum, build ID and source commit. If the bytes differ, do not relabel the new build as the promoted artifact. Re-run the release transition from the already accepted bytes or restart the approval process for the new build.

8. Performance: diagnose the causal layer

Do not increase heap because a remote registry is slow, and do not invalidate proxy cache because a Maven client is reusing its own local repository. Measure the layer that owns the symptom.

9. Least-destructive repair checklist

• Wrong write target → correct the publisher URL to a hosted repository.
• Wrong group order → restore documented order; verify with a synthetic collision.
• Remote temporarily unavailable → preserve cached availability; let auto-blocking/retry behavior work; repair remote/network cause.
• Confirmed negative-cache miss → use supported cache invalidation when immediate recheck is justified.
• Internal namespace falling through → add routing/client/network governance, not an insecure public workaround.
• Checksum drift after “promotion” → stop release, compare accepted identities, and promote exact bytes.

Knowledge check

10. Summary

Topology failures become manageable when you preserve the request, identify the repository role, inspect group order and authorization, then separate client cache, Nexus cache, upstream, database/blob and runtime evidence. The checkpoint combines those skills into a fresh topology and an exact-byte promotion drill.

Official references and version notes

• Download Nexus Repository and Nexus Repository 3 Versions Status — re-check the self-hosted release line before running the pinned lab.
• Repository Types — hosted, proxy and group semantics, nested/transitive groups, ordered member lookup, and direct-member privilege boundaries.
• Configurable Repository Fields — proxy remote storage, component/metadata age, negative cache, blocking, and auto-blocking.
• Repository Actions — current cache invalidation behavior and what it does not delete.
• Repositories API — repository inventory and format/type-specific repository configuration endpoints.
• Components API, Assets API, and Search API — upload plus independent component/asset evidence.
• Maven Repositories — Maven hosted/proxy/group configuration semantics and Central proxy use.
• Routing Rules — controlling proxy requests and preventing internal namespaces from falling through to public remotes.
• Staging and the current feature matrix — Nexus staging/build-promotion is a Pro capability; the mandatory Community lab uses exact-byte copy semantics instead.

Version-sensitive statements were rechecked against Sonatype primary documentation on 2026-08-26. The mandatory path pins the same self-hosted Community lab baseline used by Chapters 02–03: Nexus Repository 3.94.1-06, Java 21, one loopback single-node instance, embedded H2 only for disposable learning, and the default file blob store. Production database/storage decisions are deferred to Chapter 05. Re-check the current download/status/release-note pages before execution.