A simple and fast URL shortener with built in stats. Requires Redis and assumes it is local for lowest possible latency.
Copy env.example to .env and set the values. For the
SECRET_TOKEN you can generate one with $ crystal eval "puts Random::Secure.hex(32)".
NOTE: If building in release mode for production, ensure KEMAL_ENV is uncommented in .env and set to production.
Then run:
shards install
crystal run src/mpngin.crFor production, make a release build with KEMAL_ENV uncommented in .env and set to production:
# Assumes .env file is correctly filled out, including KEMAL_ENV=production
shards build --production --release --static --progressThe .env must accompany the built binary at the same filesystem level. Example production tree:
mpngin
|_ mpngin (binary)
|_ .env
Creating an short URL and getting the stats require an application key first.
- Create an application first:
➜ curl -X "POST" "http://localhost:7001/application" -H "Authorization: bearer <SECRET_TOKEN_HERE>"
# New app key response
d48655ff210c3e9e4ed8f6ad4f1923a3- Use the app key in place of the
SECRET_TOKENto make shortened URLs, passing in the final redirect to URL as aapplication/x-form-urlencodedbody param namedredirect_url:
➜ curl -X "POST" "http://localhost:7001/" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "redirect_url=https://www.nintendo.com"
# Your shiny new shortened redirect URL
http://localhost:7001/541450- Get number of requests for this shortened URL:
➜ curl "http://localhost:7001/541450/stats" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
-H 'Accept: text/plain'
# Request count response
1337You can change the top-level short link domain at request time via the short_url parameter when creating a short link. For example, if normally you use mpng.in for the short URL but want to use thehorde.org instead on a per-request basis, you can easily do so:
➜ curl -X "POST" "http://localhost:7001/" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "redirect_url=https://www.nintendo.com" \
--data-urlencode "short_url=https://thehorde.org"
# Your shiny new shortened redirect URL with custom short domain
https://thehorde.org/f1274eNote: Short codes are unique per short URL
To get more detailed information, you can also inspect a link to get info such as the expanded link and request count with a report timestamp in which ever format you need:
# For JSON:
➜ curl "http://localhost:7001/541450/inspect.json" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
{"short_link":...}
# For HTML:
➜ curl "http://localhost:7001/541450/inspect.html" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
<!doctype html>
<html lang="en">
...
# For CSV:
➜ curl "http://localhost:7001/541450/inspect.csv" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
"Short Link","Expanded Link","Request Count","Report Date"
"..."MPNGIN can generate a link report in JSON, CSV, or HTML format. Use your SECRET_TOKEN to request the report endoint in which ever format you need:
# For JSON:
➜ curl "http://localhost:7001/report.json" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
[{"short_link":...}]
# For HTML:
➜ curl "http://localhost:7001/report.html" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
<!doctype html>
<html lang="en">
...
# For CSV:
➜ curl "http://localhost:7001/report.csv" \
-H 'Authorization: bearer d48655ff210c3e9e4ed8f6ad4f1923a3' \
# Response
"Short Link","Expanded Link","Request Count"
"..."MPNGIN uses ECR to generate a plain table styled by Bootstrap. You can customize the layout (src/views/layouts/layout.ecr) or the table itself (src/views/report.ecr).
You can change the file name provided for the downloaded CSV by setting LINK_REPORT_CSV_NAME ENV variable (without extension). See the env.sample file.
Note: All downstream applications get the same report. That is, short links are not scoped to downstream applications.
For spec tests:
KEMAL_ENV=test crystal specTo run static analysis checks, use locally installed Ameba (comes with shards install):
./bin/ameba
- Fork it ( https://github.com/thewalkingtoast/mpngin/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
- thewalkingtoast Adam Radabaugh - creator, maintainer