# podero-reddit — Reddit RSS proxy

Fetches recent posts from a subreddit and returns them as clean JSON. Use it when you can't
reach reddit.com directly.

This guide is served live at **https://podero-reddit.nordquant.com/** (also `/readme.md`).

## Request

```
GET https://podero-reddit.nordquant.com/reddit/feed?sub=<subreddit>&key=<secret>
```

| Param   | Required | Default | Notes |
|---------|----------|---------|-------|
| `sub`   | yes      |         | Subreddit name only, e.g. `DeutschePhotovoltaik` (no `r/`, no URL) |
| `key`   | yes      |         | Shared secret, given to you out of band. Never put it in logs or output |
| `sort`  | no       | `new`   | `new` or `top` |
| `t`     | no       | `day`   | Time window for `sort=top`: `hour`, `day`, `week`, `month`, `year`, `all`. Ignored for `new` |
| `limit` | no       | `25`    | 1–100 |

Example:

```bash
curl -s --max-time 600 "https://podero-reddit.nordquant.com/reddit/feed?sub=DeutschePhotovoltaik&sort=top&t=week&limit=50&key=$REDDIT_PROXY_SECRET"
```

## Response

```json
{
  "sub": "DeutschePhotovoltaik",
  "sort": "new",
  "t": null,
  "status": "ok",
  "fetched_at": "2026-10-08T12:34:00Z",
  "waited_seconds": 0,
  "posts": [
    {
      "title": "...",
      "link": "https://www.reddit.com/r/.../comments/...",
      "author": "username",
      "published": "2026-10-08T09:12:00Z",
      "summary_html": "<raw HTML from the feed's <content> element>"
    }
  ]
}
```

`summary_html` is raw HTML. Strip or summarize it yourself.

| `status`         | HTTP | Meaning | What to do |
|------------------|------|---------|------------|
| `ok`             | 200  | Posts returned | — |
| `no_posts`       | 200  | Feed fetched fine but had no entries | Nothing new; move on |
| `not_found`      | 200  | Subreddit doesn't exist, is banned, or the name is invalid | Check the spelling; don't retry |
| `rate_limited`   | 503  | Reddit kept refusing us, or the queue was too long to answer in time | Wait `retry_after_seconds` (also in the `Retry-After` header), then try **once** |
| `upstream_error` | 502  | Reddit unreachable, blocked us, or sent garbage | Try again later, at most once |
| —                | 403  | `{"detail": "forbidden"}`: missing or wrong `key` | Fix the key; retrying won't help |

## Rate limits: read this before you call

Reddit gives anonymous clients about **one request per minute**. The proxy handles this for
you, so you **don't need sleep/retry logic of your own**. But it does mean responses can be
slow:

- **Every call is queued, not refused.** All callers share one first-in, first-out queue in
  front of Reddit. If five requests arrive at once, they're answered one after another, about a
  minute apart. The last one may take around 5 minutes. A slow answer is normal, not an error.
- **Set your HTTP timeout to at least 600 seconds.** The proxy answers within ~9 minutes, with
  posts or with `rate_limited` plus `retry_after_seconds`. It never leaves a request hanging.
- **Repeats are free.** Results are cached for **10 minutes**, keyed on `(sub, sort, t, limit)`.
  Asking for the same feed again within that window returns instantly without touching Reddit.
  Use the same `limit` each time to get cache hits.
- **Call sequentially, not in parallel.** Parallel calls don't finish sooner; they only queue up.
  For several subreddits, request them one after another.
- **Don't hammer on `rate_limited`.** The proxy has already retried with backoff
  (30s → 60s → 120s). Honour `retry_after_seconds`, then retry once.
- **Budget:** about 50 distinct feeds per hour. Plan bigger runs around that, or reuse cached
  results.

`waited_seconds` in each response tells you how long your request sat in the queue.

## Health

`GET https://podero-reddit.nordquant.com/health` (no key):

```json
{"status": "ok", "secret_configured": true, "queued": 0, "next_upstream_slot_in_seconds": 0}
```

`queued` is how many feed requests are waiting right now. `next_upstream_slot_in_seconds`
shows when the proxy may next call Reddit. Check these before a big batch if you want a
time estimate.

## Operator notes

- Code: `podero-reddit/` in base-infra. Deployed via Ansible with the rest of the stack.
- Secret: `REDDIT_PROXY_SECRET` in `.env`. Rotate it by editing `.env` and redeploying.
- Prometheus job `podero-reddit` scrapes `/metrics` on the docker network; that path is not
  routed publicly. Alerts: `PoderoRedditDown`, `PoderoRedditSecretMissing`.
- Unit tests: `~/.venv/bin/python -m pytest podero-reddit/test_app.py -c /dev/null`.