Skip to content

Latest commit

 

History

History
243 lines (208 loc) · 10.3 KB

README.md

File metadata and controls

243 lines (208 loc) · 10.3 KB
Raw
Farside

Contents

  1. About
  2. Demo
  3. How It Works
  4. Cloudflare
  5. Development
    1. Compiling
    2. Environment Variables

About

A redirecting service for FOSS alternative frontends.

Farside 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.

Farside also integrates smoothly with basic redirector extensions in most browsers. For an simple example setup, refer to the wiki.

Demo

Farside's links work with the following structure: farside.link/<service>/<path>

For example:

Service Page Farside Link
Libreddit /r/popular https://farside.link/libreddit/r/popular
Teddit /r/popular https://farside.link/teddit/r/popular
Nitter User Profile https://farside.link/nitter/josevalim
Invidious Home Page https://farside.link/invidious
Piped Video Page https://farside.link/piped/watch?v=eBGIQ7ZuuiU
Whoogle Search "Elixir" https://farside.link/whoogle/search?q=elixir&lang_interface=en
SearX Search "Redis" https://farside.link/searx/search?q=redis
SearXNG Search "EFF" https://farside.link/searxng/search?q=EFF
SimplyTranslate Translate "hola" https://farside.link/simplytranslate/?engine=google&text=hola
Lingva Translate "bonjour" https://farside.link/lingva/auto/en/bonjour
Rimgo View photo album https://farside.link/rimgo/a/H8M4rcp
Scribe View Medium post https://farside.link/scribe/@ftrain/big-data-small-effort-b62607a43a8c

Note: This table doesn't include all available services. For a complete list of supported frontends, see: https://farside.link

Farside also accepts URLs to "parent" services, and will redirect to an appropriate front end service, for example:

How It Works

The app runs with an internally scheduled cron task that queries all instances for services defined in services.json every 5 minutes. For each instance, as long as the instance takes <5 seconds to respond and returns a successful response 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
  • /: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
      • If the service provided is actually a URL to a "parent" service (i.e. "youtube.com" instead of "piped" or "invidious"), Farside will determine the correct frontend to use for the specified URL.
    • Note that a path is not required. /libreddit for example will still redirect the user to a working libreddit instance
  • /_/:service/*glob
    • Achieves the same redirect as the main /:service/*glob endpoint, but preserves a short landing page in the browser's history to allow quickly jumping between instances by navigating back.
    • Ex: /_/nitter -> nitter instance A -> (navigate back one page) -> nitter instance B -> ...
    • Note: Uses Javascript to preserve the page in history

When a service is requested with the /:service/... endpoint, Farside requests the list of working instances from the db and returns a random one from the list and adds that instance as a new entry in the db 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.

Regarding Cloudflare

Instances for each supported service that are deployed behind Cloudflare are not included when using farside.link. If you would like to also access instances that use Cloudflare (in addition to instances that do not), you can either use cf.farside.link instead, or deploy your own instance of Farside and set FARSIDE_SERVICES_JSON=services-full.json when running.

If you do decide to use cf.farside.link or use the full instance list provided by services-full.json, please be aware that Cloudflare takes steps to block site visitors using Tor (and some VPNs), and that their mission to centralize the entire web behind their service ultimately goes against what Farside is trying to solve. Use at your own discretion.

Development

To run Farside without compiling, you can perform the following steps:

  • Install dependencies: mix deps.get
  • Initialize db contents: FARSIDE_CRON=0 mix run -e Farside.Instances.sync
  • Run Farside: mix run --no-halt
    • Uses localhost:4001

Compiling

You can create a standalone Farside app using the steps below. In the example, the Farside executable is copied to /usr/local/bin, but can be moved to any preferred destination. Note that the executable still depends on the C runtime of the machine it is built on, so if you want a more portable binary, you should build Farside on a system with older library versions.

MIX_ENV=cli && mix deps.get && mix release
cp _build/cli/rel/bakeware/farside /usr/local/bin
sudo chmod +x /usr/local/bin/farside
farside

Environment Variables

Name Purpose
FARSIDE_TEST If enabled, bypasses the instance availability check and adds all instances to the pool.
FARSIDE_PORT The port to run Farside on (default: `4001`)
FARSIDE_DATA_DIR The path to the directory to use for storing instance data (default: `/tmp`)
FARSIDE_SERVICES_JSON The JSON file to use for selecting instances (default: `services.json`)
FARSIDE_CRON Set to 0 to deactivate the scheduled instance availability check (default on).