短褲 Shorts

A lightweight URL shortener built with Go. 中文版本

Features

Hot-Reloading Configuration

Edit the config/redirects.toml file and Shorts will automatically reload the configuration.

# config/redirects.toml

[temporary]
"discord" = "https://discord.gg/9yYtgA4HXz"

[permanent]
"google" = "https://www.google.com"

Temporary and Permanent Redirects

Add experimental redirects as temporary redirects (307) and change them to permanent redirects (301) for faster redirection.

With the above configuration:

curl -v localhost:8080/discord

< HTTP/1.1 302 Found
< Content-Type: text/html; charset=utf-8
< Location: https://discord.gg/9yYtgA4HXz
< Date: Sun, 08 Sep 2024 14:28:11 GMT
< Content-Length: 52
< 
<a href="https://discord.gg/9yYtgA4HXz">Found</a>.

curl -v localhost:8080/google

< HTTP/1.1 301 Moved Permanently
< Content-Type: text/html; charset=utf-8
< Location: https://www.google.com
< Date: Mon, 09 Sep 2024 08:38:22 GMT
< Content-Length: 57
< 
<a href="https://www.google.com">Moved Permanently</a>.

Viewing Statistics

Shorts records the number of visitors and the last visited time for each redirect in config/stats.json.

{
  "discord": {
    "visitors": 1,
    "last_visited": "2024-09-08T22:28:11.894270007+08:00"
  },
  "google": {
    "visitors": 1,
    "last_visited": "2024-09-09T16:38:22.113075596+08:00"
  }
}

API Features

Try Redirect API

The /api/try endpoint allows you to attempt to redirect to a slug and fall back to a specified URL if the slug is not found. This API requires two parameters: slug (the redirect to try) and fallback (a complete URL to redirect to if the slug doesn't exist).

curl -v "localhost:8080/api/try?slug=discord&fallback=not-found"

< HTTP/1.1 302 Found
< Content-Type: text/html; charset=utf-8
< Location: https://discord.gg/9yYtgA4HXz
< Date: Sun, 10 Sep 2024 15:30:22 GMT
< Content-Length: 52
< 
<a href="https://discord.gg/9yYtgA4HXz">Found</a>.

If the slug doesn't exist, it will redirect to the fallback path on the same domain:

curl -v "localhost:8080/api/try?slug=nonexistent&fallback=not-found"

< HTTP/1.1 302 Found
< Content-Type: text/html; charset=utf-8
< Location: http://localhost:8080/not-found
< Date: Sun, 10 Sep 2024 15:31:45 GMT
< Content-Length: 56
< 
<a href="http://localhost:8080/not-found">Found</a>.

Deployment

We recommend deploying Shorts using Docker.

Docker

docker run -d -p 8080:8080 \
  -v $PWD/config:/config \
  ghcr.io/ntut-npc/shorts

Docker Compose

See docs/compose.yaml for an example Docker Compose configuration.

Development

To set up Shorts for local development:

1. Clone the repository:

   git clone https://github.com/ntut-npc/shorts.git
   cd shorts

2. Run the dev script:

   scripts/dev.sh

The server will start on http://localhost:8080. Remember to create and configure your config/redirects.toml file as described in the Hot-Reloading Configuration section to set up your redirects.