Docs: add troubleshooting for Simple API JSON mirroring (#2145)

* Docs: add troubleshooting for Simple API JSON mirroring

* Build(deps): Bump s3path from 0.6.4 to 0.6.5 (#2147)

Bumps [s3path](https://github.com/liormizr/s3path) from 0.6.4 to 0.6.5.
- [Release notes](https://github.com/liormizr/s3path/releases)
- [Commits](liormizr/s3path@0.6.4...0.6.5)

---
updated-dependencies:
- dependency-name: s3path
  dependency-version: 0.6.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Build(deps): Bump packaging from 25.0 to 26.0 (#2146)

Bumps [packaging](https://github.com/pypa/packaging) from 25.0 to 26.0.
- [Release notes](https://github.com/pypa/packaging/releases)
- [Changelog](https://github.com/pypa/packaging/blob/main/CHANGELOG.rst)
- [Commits](pypa/packaging@25.0...26.0)

---
updated-dependencies:
- dependency-name: packaging
  dependency-version: '26.0'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>

* Build(deps): Bump coverage from 7.13.2 to 7.13.3 (#2148)

Bumps [coverage](https://github.com/coveragepy/coveragepy) from 7.13.2 to 7.13.3.
- [Release notes](https://github.com/coveragepy/coveragepy/releases)
- [Changelog](https://github.com/coveragepy/coveragepy/blob/main/CHANGES.rst)
- [Commits](coveragepy/coveragepy@7.13.2...7.13.3)

---
updated-dependencies:
- dependency-name: coverage
  dependency-version: 7.13.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>

* Build(deps): Bump setuptools from 80.10.2 to 82.0.0 (#2149)

Bumps [setuptools](https://github.com/pypa/setuptools) from 80.10.2 to 82.0.0.
- [Release notes](https://github.com/pypa/setuptools/releases)
- [Changelog](https://github.com/pypa/setuptools/blob/main/NEWS.rst)
- [Commits](pypa/setuptools@v80.10.2...v82.0.0)

---
updated-dependencies:
- dependency-name: setuptools
  dependency-version: 82.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>

* Build(deps): Bump boto3 from 1.42.40 to 1.42.44 (#2150)

* Build(deps): Bump boto3 from 1.42.40 to 1.42.44

Bumps [boto3](https://github.com/boto/boto3) from 1.42.40 to 1.42.44.
- [Release notes](https://github.com/boto/boto3/releases)
- [Commits](boto/boto3@1.42.40...1.42.44)

---
updated-dependencies:
- dependency-name: boto3
  dependency-version: 1.42.44
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* Update botocore version to 1.42.44

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>

* Docs: add missing changelog fragment

* Docs: address review — correct master URL, add PEP 691, JSON requirements, and fail-fast behavior

* Docs: link mirror-from-mirror Simple API guide in main index

* Docs: finalize review — fix PEP wording and add HTML fallback note

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Docs: add changelog fragment for mirror-from-mirror JSON docs

* Add changelog entry for docs: Simple API JSON troubleshooting

* Add CHANGES.md entry for PR #2145

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Move changelog entry to Unreleased and remove unused changelog.d file

* chore: remove newsfragments files per review

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

CHANGES.md

@@ -1,3 +1,9 @@
+# Unreleased
+
+## Documentation
+
+- Docs: add troubleshooting for Simple API JSON mirroring `PR #2145`
+
 # 7.1.0
 
 ## New Features

docs/index.rst

@@ -43,3 +43,4 @@ Contents
     serving
     CONTRIBUTING
     modules
+    mirror_from_mirror_simple_api

docs/mirror_from_mirror_simple_api.rst

@@ -0,0 +1,78 @@
+Mirror from a mirror (Simple API)
+=================================
+
+Bandersnatch can mirror packages from another Python package index that
+implements the Simple Repository API (PEP 503 + 691). This allows you
+to create a secondary mirror from an existing mirror instead of directly
+from PyPI.
+
+Configuration
+-------------
+
+Set the ``master`` option in your bandersnatch configuration to the **base
+URL** of the upstream mirror.
+
+Example::
+
+    [mirror]
+    master = https://example-mirror.org
+
+Bandersnatch automatically appends ``/simple`` to the configured
+``master`` URL.
+
+Requirements
+------------
+
+The upstream mirror must support:
+
+- The Simple Repository API with **PEP 691 JSON responses**
+  (``Accept: application/vnd.pypi.simple.v1+json``)
+- The PyPI JSON metadata endpoint:
+  ``/pypi/<project>/json``
+
+Bandersnatch requires JSON responses for correct mirroring.
+
+Notes
+-----
+
+- Some mirrors may have partial content or different filtering rules.
+- Synchronization speed depends on the upstream mirror performance.
+- If the upstream serves only HTML Simple API (PEP 503) and not JSON, mirroring will fail (no automatic fallback).
+
+
+JSON vs HTML behavior
+---------------------
+
+Bandersnatch **only supports the JSON Simple API (PEP 691)**.
+
+If the upstream mirror serves only HTML (PEP 503) and does not provide
+JSON responses, bandersnatch will **fail fast** instead of falling back
+to HTML parsing.
+
+Use cases
+---------
+
+- Creating an internal mirror from an organizational mirror
+- Reducing load on PyPI by chaining mirrors
+- Regional or offline mirror setups
+
+Troubleshooting
+---------------
+
+Bandersnatch 7.0+ uses the PEP 691 Simple API JSON format when available.
+
+If the upstream mirror does not return JSON and instead serves HTML,
+bandersnatch may fail with errors such as:
+
+aiohttp.client_exceptions.ContentTypeError:
+Attempt to decode JSON with unexpected mimetype: text/html
+
+To verify JSON support, check:
+
+- The ``/simple/`` endpoint responds with JSON when requested with:
+
+  Accept: application/vnd.pypi.simple.v1+json
+
+- The response ``Content-Type`` is:
+
+  application/vnd.pypi.simple.v1+json