https://github.com/lukehsiao/openring-rs
:chains: a webring for static site generators written in Rust
https://github.com/lukehsiao/openring-rs
atom openring rss rust static-site webring
Last synced: 4 months ago
JSON representation
:chains: a webring for static site generators written in Rust
- Host: GitHub
- URL: https://github.com/lukehsiao/openring-rs
- Owner: lukehsiao
- License: other
- Created: 2022-08-05T02:50:25.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-07-21T00:06:28.000Z (11 months ago)
- Last Synced: 2025-07-21T00:25:37.707Z (11 months ago)
- Topics: atom, openring, rss, rust, static-site, webring
- Language: Rust
- Homepage: https://luke.hsiao.dev/blog/openring-rs/
- Size: 344 KB
- Stars: 20
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
⛓
openring-rs
A tool for generating a webring from Atom/RSS feeds.
`openring-rs` is a tool for generating a webring from Atom/RSS feeds, so you can populate a template with articles from those feeds and embed them in your own blog. An example template is provided in `in.html`.
This is a Rust-port of Drew DeVault's [openring](https://git.sr.ht/~sircmpwn/openring), with the primary differences being:
- we respect throttling and send conditional requests by default via caching (disable with `--no-cache`)
- the template is written using [Tera](https://keats.github.io/tera/) and is provided as an argument, not read from stdin
- we show a little progress bar
- we fetch all feeds concurrently
- we provide better error messages (via [miette](https://github.com/zkat/miette))
- we allow filtering feeds with `--before`
## Demo
To see this in action, you can look at the footer of this blog post.
## Install
```
cargo install --locked openring
```
## Usage
```
A webring for static site generators written in Rust
Usage: openring [OPTIONS] --template-file
Options:
-n, --num-articles Total number of articles to fetch [default: 3]
-p, --per-source Number of most recent articles to get from each feed [default: 1]
-S, --url-file File with URLs of Atom/RSS feeds to read (one URL per line, lines starting with '#' or "//" are ignored)
-t, --template-file Tera template file
-s, --url A single URL to consider (can be repeated to specify multiple)
-b, --before Only include articles before this date (in YYYY-MM-DD format)
--no-cache Do NOT use request cache stored on disk
--max-cache-age Discard all cached requests older than this duration [default: 30d]
-v, --verbose... Increase logging verbosity
-q, --quiet... Decrease logging verbosity
-h, --help Print help (see more with '--help')
-V, --version Print version
```
## Using Tera templates
The templates supported by `openring-rs` are written using [Tera](https://keats.github.io/tera/).
Please refer to the Tera documentation for details.
## Caching
We use OS-standard locations for caching.
- **Linux**: `$XDG_CACHE_HOME/openring/cache.json` or `$HOME/.cache/openring/cache.json`
- **macOS**: `$HOME/Library/Caches/dev.hsiao.openring/cache.json`
- **Windows**: `{FOLDERID_LocalAppData}\hsiao\openring\cache\cache.json`
The cache file is simple JSON.
The cache only prevents refetching a feed if the feed source responds with a 429.
In this case, we respect `Retry-After`, or default to 4 hours.
Otherwise, we use the cache to send conditional requests by respecting the `ETag` and `Last-Modified` headers.
## Why a Rust port?
Just for fun.
## TODO
### Test suite
I've only recently added some property-based testing to this repository for some happy-path behavior.
I'd love to make this test suite more rigorous.
The most significant hole right now is all the log in `src/lib.rs` which handles variables nuances of a feed body.
The test suite only contains a single valid RSS 2.0 feed.
It would be great to generate test strategies that provide far more coverage of both RSS and Atom feeds.
Another thing that is interesting is the potential holes revealed by `cargo-mutant`.
We've added a GitHub workflow for it to show the holes.
Finally, `proptest` tests for `src/feedfetcher.rs` are excessively slow.
We should be able to speed those up.