tts-proxy

A simple server for forwarding/proxying Tabletop Simulator web requests into standard HTTP.

Why?

At present, Tabletop Simulator's WebRequest API is extremely limited and doesn't let you read or write headers, and in the case of POSTs doesn't even let you set the request body.

Basically, this means that by default TTS is completely unable to consume the vast majority of third-party web APIs - in particular RESTful APIs are impossible to use directly with TTS' WebRequest.

This is where tts-proxy comes in. Instead of communicating with an API directly, tts-proxy acts as an "translator" which takes a TTS web request, and creates a standard HTTP request on your behalf. When the response comes back, tts-proxy does the opposite, converting a standard HTTP response into something you can read inside Tabletop Simulator.

How do I use this?

As much as it'd be nice to have one pre-setup all TTS mods could share, if we all start using it the traffic could become too significant and it'd either get very slow, or become very expensive to maintain (throwing more resources at it).

So, to alleviate this issue, the idea is that each mod (or each mod developer) would have their own tts-proxy instance running on Heroku. Heroku have a free tier that should be more than enough for any one TTS mod; so there's no cost involved.

The only hiccup is that you need some way of deploying your own copy of tts-proxy. Lucky for you, that big purple "Deploy" button at the top of this page will completely automate the process for you. Yay!

NOTE: You will need a Heroku account, but these are free and do not require credit card details.

Security

Anyone hosting your mod will need to be able to communicate with tts-proxy. However, you probably don't want other mods (or random applications) using your proxy!

To mitigate this, we allow you restrict which URLs your tts-proxy deployment is capable of communicating with. If you restrict tts-proxy to communicate with services/URLs that are specific to your mod, then your deployment can't be abused by third-parties trying to use your proxy for other purposes.

We keep it simple and provide just one option (environment variable) you need to set, called URL_REGEX. You can update URL_REGEX from https://dashboard.heroku.com/apps/<YOUR_HEROKU_DEPLOYMENT_NAME>/settings.

IMPORTANT: By default URL_REGEX has the value .+ which means any URL i.e. By default tts-proxy is not restricted.

As an example, if you wanted to use Firebase Cloud Firestore as a datastore for your mod, you could restrict tts-proxy to communicating with just your Firestore database with:

URL_REGEX=https://firestore\.googleapis\.com/v1beta1/projects/<YOUR_PROJECT_ID>/.+

This is called a regular expression, specifically it's using Python regular expression syntax.

Note: You may be wondering why we just don't offer password protection, or encryption. For that to work you'd need to distribute the secret as part of your TTS workshop mod. Meaning to obtain your "secret", all someone would need to do is go looking through your mod!

Manual Deployment

If for some reason you don't want to deploy automatically (using the "Deploy" button at the top of the page) you can also deploy manually by following the following procedure.

1. Clone tts-proxy:

   git clone https://github.com/Benjamin-Dobell/tts-proxy.git

2. Create a Heroku app:

   heroku create

3. Deploy tts-proxy to your Heroku app:

   git push heroku master

4. Ensure one "Dyno" (app instance) is running:

   heroku ps:scale web=1

Tabletop Simulator HTTP Client

The corresponding Tabletop Simulator Lua HTTP client for this proxy is available as part of ge_tts.