bunnysign

README

bunny-sign

Go library for BunnyCDN token authentication, signed URLs, and edge cache purging.

Features

• URL path signing with HMAC-SHA256 and fast paths for query-free URLs
• Directory token paths (token_path) and sorted query parameter signing
• Client IP restriction with automatic port stripping and IPv4-mapped IPv6 unmapping
• Signature verification using constant-time comparisons
• Cache purging for individual URLs, cache tags, and entire pull zones
• Standard library only, no external dependencies

Installation

go get github.com/fumbledlol/bunny-sign

Quick start

Signing URLs

package main

import (
	"fmt"
	"time"

	bunnysign "github.com/fumbledlol/bunny-sign"
)

func main() {
	baseURL := "https://cdn.example.com"
	filePath := "/videos/1080p/intro.mp4"
	secretKey := "your-bunny-token-key"

	// Sign with 2-hour TTL
	signedURL := bunnysign.Sign(baseURL, filePath, secretKey, bunnysign.Options{
		TTL: 2 * time.Hour,
	})
	fmt.Println("Signed URL:", signedURL)

	// Sign restricted to client IP
	signedIPURL := bunnysign.Sign(baseURL, filePath, secretKey, bunnysign.Options{
		TTL:    1 * time.Hour,
		UserIP: "203.0.113.19",
	})
	fmt.Println("IP-restricted URL:", signedIPURL)
}

Verifying signed URLs

valid, err := bunnysign.Verify(signedURL, secretKey, clientIP)
if err != nil || !valid {
	// Expired or invalid token
}

Edge cache purge API

client := bunnysign.NewPurgeClient("your-api-key", bunnysign.WithPullZoneID("12345"))

// Purge specific URLs
err := client.PurgeURL(ctx, "https://cdn.example.com/asset.png")

// Purge edge cache tags
err = client.PurgeCacheTag(ctx, "12345", "user-profiles", "avatars")

// Purge entire pull zone
err = client.PurgePullZone(ctx, "12345")

Benchmarks

BenchmarkSign-12        1410318    856.1 ns/op     776 B/op    10 allocs/op
BenchmarkVerify-12       796447   1719   ns/op    1200 B/op    14 allocs/op

License

MIT

Documentation

Index

• Variables
• func Sign(baseURL, filePath, secret string, opts Options) string
• func Verify(rawURL, secret string, userIP string) (bool, error)
• type ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithPullZoneID(id string) ClientOption
• type Options
• type PurgeClient
  • func NewPurgeClient(apiKey string, opts ...ClientOption) *PurgeClient
  • func (c *PurgeClient) PurgeCacheTag(ctx context.Context, pullZoneID string, tags ...string) error
  • func (c *PurgeClient) PurgePullZone(ctx context.Context, pullZoneID string) error
  • func (c *PurgeClient) PurgeURL(ctx context.Context, urls ...string) error

Variables

var (
	// ErrExpired indicates a signed URL token has expired.
	ErrExpired = errors.New("bunnysign: token expired")
	// ErrInvalidSignature indicates the signature does not match.
	ErrInvalidSignature = errors.New("bunnysign: invalid signature")
	// ErrMissingToken indicates the URL does not contain a signature token.
	ErrMissingToken = errors.New("bunnysign: missing token parameter")
	// ErrMissingExpires indicates the URL does not contain an expiration timestamp.
	ErrMissingExpires = errors.New("bunnysign: missing expires parameter")
)

Functions

func Sign

func Sign(baseURL, filePath, secret string, opts Options) string

Sign signs a URL path with BunnyCDN HMAC-SHA256 token authentication. If secret is empty, the plain joined URL is returned.

func Verify

func Verify(rawURL, secret string, userIP string) (bool, error)

Verify validates a signed BunnyCDN URL against the secret and optional client IP.

Types

type ClientOption

type ClientOption func(*PurgeClient)

ClientOption configures a PurgeClient.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient overrides the HTTP client.

func WithPullZoneID

func WithPullZoneID(id string) ClientOption

WithPullZoneID sets the default pull zone ID.

type Options

type Options struct {
	// Expires sets the absolute expiration time. Takes precedence over TTL.
	Expires time.Time
	// TTL is added to the current time to compute the expiration timestamp.
	TTL time.Duration
	// UserIP optionally restricts the token to a specific client IP address.
	UserIP string
	// TokenPath specifies an optional directory path to sign instead of the full file path.
	TokenPath string
	// UseHourlyCache truncates the expiration time to the current hour for deterministic caching.
	UseHourlyCache bool
}

Options specifies URL signing parameters.

type PurgeClient

type PurgeClient struct {
	// contains filtered or unexported fields
}

PurgeClient interacts with the Bunny.net purge API.

func NewPurgeClient

func NewPurgeClient(apiKey string, opts ...ClientOption) *PurgeClient

NewPurgeClient creates a client for the Bunny.net cache purge API.

func (*PurgeClient) PurgeCacheTag

func (c *PurgeClient) PurgeCacheTag(ctx context.Context, pullZoneID string, tags ...string) error

PurgeCacheTag invalidates cached items matching one or more Edge Cache Tags.

func (*PurgeClient) PurgePullZone

func (c *PurgeClient) PurgePullZone(ctx context.Context, pullZoneID string) error

PurgePullZone invalidates the entire cache for a pull zone.

func (*PurgeClient) PurgeURL

func (c *PurgeClient) PurgeURL(ctx context.Context, urls ...string) error

PurgeURL invalidates specific cached URLs across Bunny.net edge nodes.