- Notifications
You must be signed in to change notification settings - Fork20
Golang URL shortener and bookmarker service with UI, API, Cache, Hits Counter and forwarder using postgres and redis in backend, bulma in frontend. Think of it as self hosting ready url shortener.
License
adhocore/urlsh
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
urlsh is URL shortener application built onGo language.
It does not use external libraries except thegorm
forpostgres
database and minimal redismoduleredigo.
Just visit the homepage of your urlsh deployment site. You can also integrate API for programmatic usage.
If you live inside the command line terminal, you can install a client:
go get github.com/adhocore/urlsh/cmd/urlshc
or, with newer go versions
go install github.com/adhocore/urlsh/cmd/urlshc
Make sure$GOPATH
or$HOME/go/bin
is in your$PATH
or%path%
, then use it like so:
# show helpurlshc -h# shorten a urlurlshc -url'https://your.long.url/here'# shorten a url with keywords and expiry dateurlshc -url'https://your.long.url/here' -keywords'word-1,word2' -expires'2022-12-31'# if you have self hosted or local instance of urlsh, pass in URLSH_HOST (with domain only)URLSH_HOST=https://your.urlsh-instance.com urlshc -url'https://your.long.url/here'
Read below for self hosting, API integration and/or contributing tourlsh.
git clone git@github.com:adhocore/urlsh.gitcd urlsh
It should be configured using env variables.
Please check.env.example for available variables and explanation.
DATABASE_URL
is always required and is string of the following form:
DATABASE_URL=postgres://user:pass@host:port/dbname
When runningurlsh with docker-compose, thepreferred way,DATABASE_URL
isautomatically set fromPOSTGRES_*
variables.
Please note that
urlsh
does not ship with.env
loader so to run it in bare metal,one needs to useexport KEY=VALUE
orsource .env
manually.
IfREDIS_URL
is provided withredis://host:port
, then it will cache popular urls,the popularity threshold is hard coded to minimal value incommon.constant
.The cache will sync when short url is deleted and sometimes when expired.The hit counters will however sync in realtime.
To set up dockerizedurlsh
, run the commands below:
# first time onlycp .example.env .env# change auth token for admin if you want in `.env` file# APP_ADMIN_TOKEN=<something crypto secure random hash>docker-compose up
After a few seconds, you should be able to browse tolocalhost:2000.
For running tests,
docker-composeexec urlsh sh -c"APP_ENV=test go test ./..."# for coveragedocker-composeexec urlsh sh -c"APP_ENV=test go test -cover ./..."
APP_ENV=test
is not required but ensures that tests are run against clone database with name prefixed bytest_
.Normally test db is already prepared if you usedocker-compose
.
Status route for health/status check.
{"status":200,"message":"it works"}
Creates a new short code for given URL.
- url: string, required, http/https/ftp only
- expires_on: string, optional, utc date
yyyy-mm-dd hh:mm:ss
, default=9999-01-01
- keywords: array of strings, 2-25 chars each, max 10 keywords
{"url":"http://somedomain.com/some/very/long/url","expires_on":"","keywords": ["key","word"]}
{"status":200,"short_code":"qaFxz","short_url":"http://localhost:2000/qaFxz"}
If env var
APP_ALLOW_DUPE_URL
is set to 0 or empty, then trying to shorten same URL againwill return status 409 and payload will contain existingshort_code
.However if existingshort_code
is deleted, it will be shortened as usual.
Redirects the shortcode to original long URL.
In case short code exists it responds with 301 redirect.
If the short code is expired or deleted, it responds like so:
{"status":410,"message":"requested resource is not available"}
Token required inAuthorization
header like so:
Authorization: Bearer <token>
The query params areoptional.
page=<int>short_code=<str>keyword=<str>
Examples:
/api/admin/urls?short_code=somecode
/api/admin/urls?page=1&keyword=something
Response contains multiple matching url object insideurls
array.
{"status":200,"urls": [ {"short_code":"X5JkFd","origin_url":"http://somedomain.com/some/very/long/url","hits":1,"is_deleted":false,"expires_on":"9999-01-01T00:00:00Z" } ]}
Token required inAuthorization
header like so:
Authorization: Bearer <token>
Query paramshort_code
is requied.
Example:/api/admin/urls?short_code=somecode
If delete success:
{"status":200,"deleted":true}
If the code does not exist:
{"status":404,"message":"the given short code is not found"}
urlsh comes withpostman collection and environment to aid manual testing of endpoints.
Open the postman app, clickImport
at top left, selectFolder
and drag/choosepostman
folder of this repo.You may need to adjust thetoken
in postmanurlsh
env if you have configuredAPP_ADMIN_TOKEN
.
The collection comes with post/pre request hooks for requests so you can just run the endpoints one after another in postman UI.
For
redirect
request, you have to disable postman follow redirects fromSettings > General > Automatically follow redirects
.
Please checklicense file.
My other golang projects you might find interesting and useful:
- gronx - Lightweight, fast and dependency-free Cron expression parser (due checker), task scheduler and/or daemon for Golang (tested on v1.13 and above) and standalone usage.
- fast - Check your internet speed with ease and comfort right from the terminal.
- goic - Go Open ID Connect, is OpenID connect client library for Golang, supports the Authorization Code Flow of OpenID Connect specification.
- chin - A GO lang command line tool to show a spinner as user waits for some long running jobs to finish.
About
Golang URL shortener and bookmarker service with UI, API, Cache, Hits Counter and forwarder using postgres and redis in backend, bulma in frontend. Think of it as self hosting ready url shortener.