deeplink

Short link generation, click tracking, and OG preview pages for Go. Pluggable processors, Redis or in-memory storage, two dependencies.

Install

go get github.com/yinebebt/deeplink

Usage

service, err := deeplink.New(deeplink.Config{
    BaseURL:     "https://link.example.com",
    Store:       deeplink.NewMemoryStore(),
    TemplateDir: "templates/default",
})
if err != nil {
    log.Fatal(err)
}
service.Register(deeplink.RedirectProcessor{})

// Mount alongside your own routes.
mux := http.NewServeMux()
mux.Handle("/", service.Handler())
mux.HandleFunc("GET /hello", yourHandler)

log.Fatal(http.ListenAndServe(":8090", mux))

Create a short link:

curl -X POST http://localhost:8090/shorten \
  -H 'Content-Type: application/json' \
  -d '{"type":"redirect","url":"https://example.com/docs","title":"Docs"}'

Open the returned short_url in a browser.

Custom processors

Implement Processor:

type Processor interface {
    Type() string
    Process(ctx context.Context, link *Link) error
}

For custom template data, also implement Previewer:

type Previewer interface {
    Preview(link *Link) any
}

See example/custom for a working custom processor with tests.

Standalone server

A ready-to-run Redis-backed server is included:

docker compose up -d
go run ./cmd/deeplink

HTTP routes

Method	Path	Description
POST	/shorten	Create a short link
GET	/{shortID}	Preview page (or 302 redirect)
GET	/links/{type}	List links by type
GET	/links/{type}/{shortID}	Link detail with click count
GET	/health	Health check

The standalone server (cmd/deeplink) also registers:

Method	Path	Description
GET	/dashboard	Read-only link stats page (requires dashboard.html in template dir)

When any store URL is set (AndroidStoreURL, IOSStoreURL, WebFallbackURL), these are also registered:

Method	Path	Description
GET	/preview/{shortID}	Preview without auto-redirect
GET	/redirect	App store redirect by platform
GET	/.well-known/	Static files from template dir

For iOS Universal Links and Android App Links, place your apple-app-site-association and assetlinks.json files in <TemplateDir>/.well-known/.

Configuration

Environment variables for cmd/deeplink:

Variable	Default	Description
DEEPLINK_LISTEN_ADDR	:8090	Listen address
DEEPLINK_BASE_URL	http://localhost:8090/	Base URL for short links
DEEPLINK_REDIS_ADDR	localhost:6379	Redis address
DEEPLINK_REDIS_PASSWORD		Redis password
DEEPLINK_ALLOWED_ORIGINS		CORS origins (comma-separated)
DEEPLINK_TEMPLATE_DIR	templates/default	Template directory
DEEPLINK_SKIP_PATHS_FILE		Skip-path regex file
DEEPLINK_CLICK_BUFFER_SIZE	1024	Async click event buffer capacity
DEEPLINK_CLICK_FLUSH_INTERVAL	1s	How often buffered clicks are flushed to the store
DEEPLINK_API_KEY		Protect mutating endpoints (Authorization: Bearer <key> or X-API-Key: <key>)

Templates

The default templates in templates/default/ use these fields from Link:

Field	Template variable	Used for
URL	{{.URL}}	Redirect target, og:url
Title	{{.Title}}	Page title, og:title
Description	{{.Description}}	og:description
ImageURL	{{.ImageURL}}	og:image

To customize, copy templates/default/ and set TemplateDir in config.

Development

go test ./...          # run tests
go run ./cmd/deeplink  # run standalone server (needs Redis)

License

MIT