Skip to content
Projects

soulteary/rss-can has 69 GitHub stars and 4 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 00:50 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Rule-driven RSS generator in Go that converts web pages into feeds, with JavaScript rules, headless-browser rendering, and memory or Redis caching.

Creative & Media

README.md

Original

RSS Can / RSS 罐头

v0.5.0 adds optional team access, public fetch policy and a source wizard. Historical v0.4.0 does not implement these features and silently ignores their environment variables. Follow the deployment and verification steps before configuring Stargate.

For the simplest supported team setup, use the source-based Stargate Compose guide.

For a shared Stargate deployment, use team access mode to give each source explicit permissions and issue revocable reader credentials. The source wizard and rssc doctor provide a guided workflow without writing JavaScript rules.

Go Test Coverage Go Report Card CodeQL Build Artifacts Docker Image

ENGLISH | 中文文档

📰 🥫 Got RSS CAN be better and simple.

Architecture

RSS Can architecture

RSS Can parses web pages using rules and generates RSS, Atom or JSON Feed with caching. The animation shows the main call directions.

Supported Systems and Architectures

  • Linux: AMD64(x86_64) / ARM64
  • macOS: AMD64(x86_64) / ARMv64

Current release: v0.5.1. See the release notes for changes and upgrade requirements.

Usage

Download the binary from the github release page, with the following command:

./rssc

JavaScript runtime

v0.5.0 uses a persistent Deno worker by default. Install Deno 2.9.8 on PATH, or set RSS_CAN_DENO to its executable. Build with CGO_ENABLED=0 go build -o rssc .; no build tag is needed. Tests also require Deno. v0.5.0 Docker images and all four standalone archives include pinned Deno 2.9.8. Keep the bundled executable beside rssc; no separate download is needed. Historical v0.3.12 retains its embedded runtime.

The service checks every Deno worker before starting. RSS_JS_WORKERS defaults to 1 and accepts 1–16 (restart to change). Runtime lookup uses RSS_CAN_DENO, a deno executable beside rssc, then PATH. See the upgrade guide for installation, proxy/cookie behavior and concurrency limits. See runtime setup for lifecycle and deployment requirements.

Feed generation limits

The following behavior applies to v0.5.0:

  • SSR PagerLimit counts all pages, including the current page. An omitted/zero limit parses only the current page; negative values are rejected. The current document is reused, and duplicate pagination URLs (including fragment-only differences) are processed once.
  • IdByRegexp must be valid and contain at least one capture group. The first capture of the first match becomes the entry ID; a non-match leaves the ID unset. Invalid patterns produce a rule configuration error.
  • RSS_SERVER_TIMEOUT / -timeout-server bounds the entire feed generation pipeline: JS queueing/startup, rule evaluation, cache access, SSR/CSR/mixed parsing, pagination, detail requests and serialization. Per-request, JS and browser timeouts may end individual steps sooner. Decoded SSR and detail-page HTML is limited to 10 MiB per document.
  • Unsupported feed types return 400; unknown rules return 404; rule or feed generation errors return 500; upstream failures return 502; the overall deadline returns 504 without a partial feed. Owner quota exhaustion returns 429; global capacity exhaustion returns 503.

Docker

Pull the docker image and mount the Feed rules file in the project to the docker container:

docker pull soulteary/rss-can:v0.5.1
docker run --rm -it --user 65532:65532 -p 127.0.0.1:8080:8080 -e RSS_REDIS=false -v "$(pwd)/rules:/rules:ro" soulteary/rss-can:v0.5.1

This command starts standalone mode. For bounded CPU/memory and a read-only root filesystem, use the standalone Compose examples. Team access requires the additional Stargate configuration; an image upgrade alone does not enable it.

The Docker Hub image supports Linux AMD64/ARM64. Images include example rules; add -e RSS_REDIS=false for memory-only caching. Binary archives include rssc, rules/, documentation and license notices. Verify downloads with the accompanying SHA-256 files.

Cli Parameters & Environment

All parameters are optional, please adjust according to your needs

The parameters supported by the program can be obtained through -h or --help:

Usage of rssc:
  -debug RSS_DEBUG
    	whether to output debugging logging, env: RSS_DEBUG
  -debug-level RSS_DEBUG_LEVEL
    	set debug log printing level, env: RSS_DEBUG_LEVEL (default "info")
  -feed-path RSS_HTTP_FEED_PATH
    	http feed path, env: RSS_HTTP_FEED_PATH (default "/feed")
  -headless-addr RSS_HEADLESS_SERVER
    	set Headless server address, env: RSS_HEADLESS_SERVER (default "127.0.0.1:9222")
  -headless-slow-motion RSS_HEADLESS_SLOW_MOTION
    	set Headless slow motion, env: RSS_HEADLESS_SLOW_MOTION (default 2)
  -host RSS_HOST
    	web service listening address, env: RSS_HOST (default "0.0.0.0")
  -memory RSS_MEMORY
    	using Memory(build-in) as a cache service, env: RSS_MEMORY (default true)
  -memory-expiration RSS_MEMORY_EXPIRATION
    	set Memory cache expiration, env: RSS_MEMORY_EXPIRATION (default 600)
  -port RSS_PORT
    	web service listening port, env: RSS_PORT (default 8080)
  -proxy RSS_PROXY
    	Proxy, env: RSS_PROXY
  -redis RSS_REDIS
    	using Redis as a cache service, env: RSS_REDIS (default true)
  -redis-addr RSS_SERVER
    	set Redis server address, env: RSS_SERVER (default "127.0.0.1:6379")
  -redis-db RSS_REDIS_DB
    	set Redis db, env: RSS_REDIS_DB
  -redis-pass RSS_REDIS_PASSWD
    	set Redis password, env: RSS_REDIS_PASSWD
  -rule RSS_RULE
    	set Rule directory, env: RSS_RULE (default "./rules")
  -timeout-headless RSS_HEADLESS_EXEC_TIMEOUT
    	set headless execution timeout, env: RSS_HEADLESS_EXEC_TIMEOUT (default 5)
  -timeout-js RSS_JS_EXEC_TIMEOUT
    	set js sandbox code execution timeout, env: RSS_JS_EXEC_TIMEOUT (default 200)
  -timeout-request RSS_REQUEST_TIMEOUT
    	set request timeout, env: RSS_REQUEST_TIMEOUT (default 5)
  -timeout-server RSS_SERVER_TIMEOUT
    	set web server response timeout, env: RSS_SERVER_TIMEOUT (default 8)

Changes to review before upgrading

Upgrade from v0.4.0 before switching traffic:

  • Feed snapshots default to 30 seconds of freshness and up to 3600 additional seconds of stale service during refresh failures. Set RSS_SNAPSHOT_TTL=0 to disable snapshots. Manual refresh fetches and replaces upstream document caches.
  • Feed HTML safety applies to every rule: active markup and CSS are removed, images become alternative text, and JSON Feed summaries are plain text.
  • Fetch policy defaults to trusted operator-owned rules in standalone mode. Team mode enforces public SSR destinations and source permissions. Each generation has a shared 64-request/64-MiB upstream budget.

Management endpoints and page inspector

/config/* and /inspector* accept direct loopback clients using a localhost or loopback-IP Host by default. Remote or reverse-proxied access requires RSS_ADMIN_TOKEN and an Authorization: Bearer <token> request header. Once a token is configured, local requests require it too. For browser access, an authenticated reverse proxy can inject the header. Cross-site management requests are rejected.

The inspector only fetches public HTTP(S) destinations, including redirects and subresources. It does not forward cookies or use a proxy. Fetched markup is displayed in an isolated sandbox. Normal feed rules retain cookie and proxy support.

Browser tasks run in isolated contexts with a concurrency limit of four. Their deadline covers queueing, connection, navigation, and script execution. Contexts are released on success and failure. SSR, CSR and mixed-mode caches are separate; CSR cache keys also include rule contents and cookies.

See dependency maintenance for pinned versions, upgrade constraints and embedded library provenance.

Running regression tests

Tests require Redis. Browser integration tests connect to the Chrome / Chromium debugging endpoint specified by RSS_TEST_BROWSER_URL; they do not download or launch a browser:

RSS_SERVER=127.0.0.1:6379 RSS_TEST_BROWSER_URL=http://127.0.0.1:9222 RSS_TEST_BROWSER_REQUIRED=1 go test -race ./... -count=1

Set RSS_TEST_BROWSER_URL to an isolated Chrome/Chromium debugging endpoint. Without it, live browser integration is skipped unless RSS_TEST_BROWSER_REQUIRED=1 is set. Tests do not launch Chrome or consume RSS_TEST_CHROME. Redis uses RSS_SERVER; cache connection settings are fixed after initialization.

Milestone

PLAN

  • Docs: Provide a simple tutorial on how to use Docker images with common technology stacks #16
  • Pipeline: Support RSS pipeline flow, customize information processing tasks and integrate other open-source software
  • AI: NLP tasks
  • Rules: Support merge open-source software rules: rss-bridge / RSSHub
  • Tools: Quick RSS rules generator, like: damoeb/rss-proxy

License & Credits

This project is licensed under the MIT License

The rapid evolution of the project is inseparable from the following excellent open source software, you can click this link to know who they are : Credits

Monitoring and load verification

/_/health/ remains a liveness check. /_/ready/ checks JS execution and cache readiness, allowing a working memory fallback when Redis is down. /_/metrics/ exports Prometheus counters, gauges and histograms for fetch failures, cache reads, JS queueing and browser occupancy under management access restrictions. See observability for definitions and queries.

Cache-enabled document requests share in-flight work; DisableCache retains independent fetches. Set RSS_CONFIG_CACHE_TTL=30 to opt into configuration caching, disabled by default for dynamic rules. Date conversions are reused only within a feed. See HTTP load measurements and testing and coverage budgets.

v0.5.0 shares immutable rule snapshots, bounds upstream HTTP work (16 active and 64 waiting; overload returns 503), bounds Redis operations with circuit recovery, and injects a FeedService. See the upgrade guide for behavior and limits.

v0.5.0 also includes a 64 MiB memory-cache budget, transactional rule reload, generation/page/item/output limits, shared browser extraction and independently owned application shutdown. Standalone mode rejects empty or invalid rule sets; team mode may start with an empty readable rule directory for the source wizard; see the upgrade guide.

Deployment profiles: Compose examples and upgrade checks.

Administrative API hardening

v0.5.0 requires POST plus X-RSS-Admin-Action: 1 for /config/* mutations. GET returns 405. Docker images run as UID/GID 65532; examples bind to loopback and mount rules read-only. See secure deployment.