FFZBot Cloudflare Worker

This is a Cloudflare Worker that exposes the @ffz/link-service project to HTTP clients.

I don't expect anyone to need to run this themselves, but if you want to run a copy of the link preview service, this is how you'd do it.

If you just want to implement a new resolver for a website, or change how a resolver works, you should check out the Link-Service project instead.

How to Use

Please note that these instructions assume you already know how to use Cloudflare's Worker platform, along with the wrangler tool.

1. Fork the project.

2. Copy wrangler.toml.example to wrangler.toml, and make the following chanages:

   1. Replace account_id with your own account_id, or just remove the line.

   2. Update the dataset in analytics_engine_datasets with the name of the dataset you want to store events in, or just remove the block to disable analytics events.

   3. Update the id in kv_namespaces to point to a KV namespace associated with your account, or just remove the block to disable Bluesky session caching. Please note that it is not recommended to do this, as Bluesky has strict login limits that a live service is very likely to run into without a session cache.

   4. Update the cache_db_name and cache_db_id in d1_databases with values for a database that you'd like to use for caching. We use D1 rather than KV for caching because low latency is less of a concern than costs, and D1 is much cheaper for this use case. Currently, the cache is only used for Fediverse lookups and it significantly cuts CPU time on subsequent hits to domains. You can disable this cache by removing the d1_databases section.

3. Make a copy of env.sample and name it .dev.vars, then update it with all the necessary API keys. If you don't have an API key for a given service just remove the relevant lines and that service's resolver will be disabled.

4. If you're using the D1 cache, execute the following command to initialize the cache table in the local database:

   wrangler d1 execute <cache_db_name> --local --file=schema.sql
   

5. Run the worker locally with pnpm dev and use our testing tool with the Provider set to "Local Dev Worker" to ensure that the service is running as expected.

   Please note that your browser will need to trust self-signed certificates from localhost or this will fail.

How to Deploy

Following along from the previous instructions:

5. Assuming everything has gone to plan, upload your secrets from .dev.vars using wrangler.

6. If you're using the D1 cache, execute the following command to initialize cache table in the production database:

   wrangler d1 execute <cache_db_name> --file=schema.sql
   

7. Finally, run pnpm wrangler deploy to deploy the worker.

About Environment Variables

Here's a quick overview of the available environment variables:

BLUESKY_IDENTIFIER

In order to use enhanced API-based functionality for Bluesky, you need to provide at a minimum BLUESKY_IDENTIFIER and BLUESKY_PASSWORD.

This is your Bluesky email address or handle, for use when authenticating against Bluesky in the event that there is no cached session to resume.

BLUESKY_PASSWORD

This is an app password for your Bluesky account. Do not use your main password. Just create an app password at: https://bsky.app/settings/app-passwords

BLUESKY_SERVICE

Optional. This is the URL used when constructing a Bluesky agent for accessing the Bluesky network. By default, if you don't provide this, the link service will use https://bsky.social

IMGUR_KEY

In order to use enhanced API-based functionality for Imgur, you need to provide an IMGUR_KEY.

This is your Imgur API key. See Imgur's API documentation for details on using the API and registering for a key.

TWITCH_ID

In order to use enhanced API-based functionality for Twitch, you need to provide at a minimum TWITCH_ID and TWITCH_SECRET.

This is your Twitch application's Client ID.

TWITCH_SECRET

This is your Twitch application's Client Secret.

YOUTUBE_KEY

In order to use enhanced API-based functionality for YouTube, you need to provide a YOUTUBE_KEY.

This is your YouTube API key.

PROXY_HOST

The link preview service is written with end-user privacy in mind, and so it's designed not to leak HTTP requests from the client to the target server. Part of that is proxying requests to images.

This should be the URL of a server running imageproxy for the construction of image URLs.

It's highly recommended you also include a PROXY_KEY to sign URLs so that bad actors cannot use your image proxy as an open redirect / open proxy.

If you want to disable image proxying behavior, and just return direct URLs, then you can set this to the special string ALLOW_UNSAFE_IMAGES.

Leaving this value out will result in images being stripped from responses.

PROXY_KEY

A secret key for signing image URLs, to be used with PROXY_HOST.

SB_SERVER

Optional. The URL to a SafeBrowsing proxy server, for doing URL safety checks.

This uses the /v4/threatMatches:find endpoint, so any server implementation you use will need to support that endpoint.