mirror of
https://github.com/benbusby/farside.git
synced 2025-03-14 19:26:30 -04:00
Update readme
Expanded readme to include a demo, a "how it works" section, and a general overview of Farside's purpose.
This commit is contained in:
parent
1ea7fdd2ec
commit
c627f4d402
64
README.md
64
README.md
@ -1,12 +1,67 @@
|
||||

|
||||
|
||||
___
|
||||
|
||||
[](https://github.com/benbusby/farside/releases)
|
||||
[](http://opensource.org/licenses/MIT)
|
||||
[](https://github.com/benbusby/privacy-revolver/actions/workflows/elixir.yml)
|
||||
|
||||
A redirecting service for FOSS alternative frontends
|
||||
A redirecting service for FOSS alternative frontends.
|
||||
|
||||
### Development
|
||||
[Farside](https://farside.link) provides links that automatically redirect to
|
||||
working instances of privacy-oriented alternative frontends, such as Nitter,
|
||||
Libreddit, etc. This allows for users to have more reliable access to the
|
||||
available public instances for a particular service, while also helping to
|
||||
distribute traffic more evenly across all instances and avoid performance
|
||||
bottlenecks and rate-limiting.
|
||||
|
||||
## Demo
|
||||
|
||||
| Service | Page | Farside Link |
|
||||
| -- | -- | -- |
|
||||
| [Libreddit](https://github.com/spikecodes/libreddit) | /r/popular | https://farside.link/libreddit/r/popular
|
||||
| [Nitter](https://github.com/zedeus/nitter) | User Profile | https://farside.link/nitter/josevalim
|
||||
| [Invidious](https://github.com/iv-org/invidious) | Home Page | https://farside.link/invidious
|
||||
| [Bibliogram](https://sr.ht/~cadence/bibliogram/) | User Profile | https://farside.link/bibliogram/u/kbdfans
|
||||
|
||||
## How It Works
|
||||
|
||||
The app runs in a container that periodically (default every 5 minutes) queries
|
||||
all instances for services defined in [services.json](services.json). For each
|
||||
instance, as long as the instance takes <5 seconds to respond and returns a 200
|
||||
status code, the instance is added to a list of available instances for that
|
||||
particular service. If not, it is discarded until the next update period.
|
||||
|
||||
Farside's routing is very minimal, with only the following routes:
|
||||
|
||||
- `/`
|
||||
- The app home page, displaying all live instances for every service
|
||||
- `/ping`
|
||||
- A passthrough "ping" to redis to ensure both app and redis are working
|
||||
- `/:service/*glob`
|
||||
- The main endpoint for redirecting a user to a working instance of a
|
||||
particular service with the specified path
|
||||
- Ex: `/libreddit/r/popular` would navigate to `<libreddit instance
|
||||
URL>/r/popular`
|
||||
- Note that a path is not required. `/libreddit` for example will still
|
||||
redirect the user to a working libreddit instance
|
||||
|
||||
When a service is requested with the `/:service/...` endpoint, Farside requests
|
||||
the list of working instances from Redis and returns a random one from the list
|
||||
and adds that instance as a new entry in Redis to remove from subsequent
|
||||
requests for that service. For example:
|
||||
|
||||
A user navigates to `/nitter` and is redirected to `nitter.net`. The next user
|
||||
to request `/nitter` will be guaranteed to not be directed to `nitter.net`, and
|
||||
will instead be redirected to a separate (random) working instance. That
|
||||
instance will now take the place of `nitter.net` as the "reserved" instance, and
|
||||
`nitter.net` will be returned to the list of available Nitter instances.
|
||||
|
||||
This "reserving" of previously chosen instances is performed in an attempt to
|
||||
ensure better distribution of traffic to available instances for each service.
|
||||
|
||||
Farside also has built-in IP ratelimiting for all requests, enforcing only one
|
||||
request per second per IP.
|
||||
|
||||
## Development
|
||||
|
||||
- Install [redis](https://redis.io)
|
||||
- Install [elixir](https://elixir-lang.org/install.html)
|
||||
@ -15,3 +70,4 @@ A redirecting service for FOSS alternative frontends
|
||||
- Initialize redis contents: `mix run update.exs`
|
||||
- Run Farside: `mix run --no-halt`
|
||||
- Uses localhost:4001
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user