Distill
Another url shortener
[]
Motivations
Existing url shorteners are not suitable for a private deploy use or are too complex in terms of requirements.
Distill aims to create a easy deployable short url service
that can be used for specific events.
Features
- Choose the alphabet set for the generate short id
- Choose the length of the generate short id
- Load existing short id <-> url mappings*
- Overwrite an existing short id with a different target url*
- Set a time to live on short ids (globally or per id)
- Set a expiration date on short ids (globabbly or per id)
- Set a request limit on short ids (globally or per id)
- Set a redirect for the
/
path
- Set a redirect url for exhausted ids (request limit reached)
- Set a redirect url for expired ids (ttl/end date reached)
- Backup/restore urls in csv or binary format
- Import data via csv
- Get statistics both globally and for short id
* the alphabet and lenght can be enforced
Expiration strategy
There are 3 ways to set an expiration for a short id:
- TTL (seconds)
- Epiration date
- Max requests
The three options can be configured globally or per short id,
the value specified for the short id takes always precedence over the
global configuration.
For the TTL and the expiration date the actual expiration is selected as
max ( creation_date + ttl, expiration_date)
!!! the expiration is set upon short id creation, changing global configuration
will not affect the short ids already set !!!
For redirects, the expiration url redirect takes precedence over the exhaustion url redirect.
If no redirects are set for exhausted / expired url then a 404
is returned.
Api Doc
Register a redirect
Miniaml request is:
POST http://localhost:1804/api/short
X-API-KEY: 123123_changeme_changeme
Content-Type: application/json
{
"url": "https://example.com/target_url"
}
Repsonse:
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Sun, 17 Mar 2019 21:18:16 GMT
Content-Length: 16
Connection: close
{
"id": "wBNaqx"
}
A request can contain additional fields:
POST http://localhost:1804/api/short
X-API-KEY: 123123_changeme_changeme
Content-Type: application/json
{
"id": "myid"
"url": "https://example.com/target_url",
"max_requests": 20,
"url_exhausted" : "https://example.com/max_requests_reached_url",
"ttl": 0,
"expire_on": "2039-03-17T22:05:28+01:00",
"url_expired" : "https://example.com/ttl_or_epiration_reached_url"
}
Repsonse:
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Sun, 17 Mar 2019 21:18:16 GMT
Content-Length: 16
Connection: close
{
"id": "myid"
}
Backup / Restore
Offline backup in csv and binary format
Import data
required fields
url
all fields
url,id,max_requests,url_exhausted,ttl,expires_on,url_expired
the dates are expressed in RFC3339 format
Configuration
TODO
Example API request
TODO
Build targets
default
build (build-dist)
clean
docker (docker-build)
docker-push
docker-run
lint
test
Development
Hints
To generate an API Token randomly use the make gen-secret
(linux/mac only):
make gen-secret
WiYS8DauSwVIMeNGIp63ScmY-pgA1ECA7ai7Oce7
Installation
Distill is distributed via different channels
Docker
Distill is available on docker hub,
as for the images:
latest
tag is built from the develop
git branch and contains the latest changes
- tags in the form
x.y.z
are built from git tags and are considered stable
to run distill in docker use the following command:
docker run -p 1804:1804 noandrea/distill
the default configuration for the docker image is available
- here for stable releases
- here for
latest
releases
Mount points
To override the configuration mount a volume in /settings.docker.yaml
path.
For the data folder the mount point is /data
.
Docker Compose
A docker-compose
example is available in the examples/docker
Systemd
Distill can be run via systemd
, check the example configuration.