From fb3e2976e24e111bf09ca4dde0b596d86cfbf9b8 Mon Sep 17 00:00:00 2001
From: Nik Afiq <nik.afiq98@ymail.com>
Date: Sun, 26 Jul 2026 01:47:07 +0900
Subject: [PATCH] feat: add documentation for JDownloader integration and
 package naming

---
 manifests/README.md            |  2 +-
 manifests/media/jdownloader.md | 54 ++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 manifests/media/jdownloader.md

diff --git a/manifests/README.md b/manifests/README.md
index 893198f..abcb055 100644
--- a/manifests/README.md
+++ b/manifests/README.md
@@ -14,7 +14,7 @@ subdirectories are consumed by Argo CD Applications in `argocd/apps`.
 | `gitea/` | Gitea storage, backup, public ingress, runner and OIDC/admin secrets |
 | `home-services/` | HA gateway, AI gateway, Discord bot, service TLS, registry secret |
 | `homeassistant/` | Home Assistant external service and ingress |
-| `media/` | Jellyfin, qBittorrent, JDownloader |
+| `media/` | Jellyfin, qBittorrent, JDownloader ([sending links](media/jdownloader.md)) |
 | `monitoring/` | Monitoring PVs, Grafana datasource, Grafana/Auth OIDC secrets |
 | `network/` | Pi-hole secrets, DDNS, Traefik dashboard, external host ingresses |
 | `portfolio/` | Portfolio deployment, ingress, registry pull secret |
diff --git a/manifests/media/jdownloader.md b/manifests/media/jdownloader.md
new file mode 100644
index 0000000..ec339ed
--- /dev/null
+++ b/manifests/media/jdownloader.md
@@ -0,0 +1,54 @@
+# Sending links to JDownloader
+
+`jdownloader` (`manifests/media/jdownloader.yaml`) runs a `cnl-bridge` sidecar
+that accepts a URL over HTTP and writes it as a `.crawljob` for JDownloader's
+FolderWatch extension to pick up. This exists because all containers in the
+pod share one network namespace, so JDownloader's own built-in Click'n'Load2
+listener (which also defaults to port 9666) can't be reached independently
+from outside the pod for this purpose.
+
+## Endpoint
+
+```
+POST https://jdownloader.home.arpa/add
+Content-Type: application/x-www-form-urlencoded
+
+urls=<the download URL>
+```
+
+Example:
+
+```bash
+curl -X POST https://jdownloader.home.arpa/add \
+  --data-urlencode "urls=https://ash-speed.hetzner.com/100MB.bin"
+```
+
+A `200 Ok.` response means the bridge wrote the `.crawljob` file.
+JDownloader's FolderWatch extension polls every ~10s, picks it up, and adds it
+directly to the Downloads list — both `autoStart` and `autoConfirm` are set,
+so it starts downloading without needing manual confirmation in the
+LinkGrabber tab.
+
+## Package naming
+
+The package name is derived automatically from the URL: the last path
+segment, with everything from the first `.` onward stripped — so
+multi-extension names collapse to the base identifier.
+
+| URL | Package name |
+| --- | --- |
+| `https://ash-speed.hetzner.com/100MB.bin` | `100MB` |
+| `https://example.com/abcdefg/1234567.mp4.html` | `1234567` |
+
+Falls back to `subyshare` if the URL has no usable path segment.
+
+## Notes
+
+- Only the first `urls` value in the POST body is used — one link per request.
+- The bridge listens on container port `9667` internally; the `Service`
+  exposes it externally as port `9666` (`targetPort: 9667`), so callers of
+  `/add` are unaffected by the internal port. The indirection exists because
+  JDownloader's own CNL2 listener already binds `9666` inside the shared pod
+  network namespace.
+- Source: the inline Python script in the `cnl-bridge` container of
+  `manifests/media/jdownloader.yaml`.