statsadmin

README

statsadmin

Embeddable admin dashboard for github.com/dracory/statsstore visitor analytics (extracted from the statsstore repository).

statsadmin.New(...) returns an http.Handler that serves a self-contained Vue.js dashboard — no frontend build step. It depends only on github.com/dracory/statsstore plus injected callbacks; it knows nothing about the host application.

Features

• Dashboard — total/unique visitors, sessions, bounce rate, avg session duration, pages per session, top paths/countries/browsers/OS/device types, recent visitors
• Visitors — paginated, filterable visitor list (IP, country, browser, OS, device type, path, date range, bot/threat flags), CSV export
• Sessions — visitor sessions grouped by IP with visit history, CSV export
• IP Details — per-IP deep dive with path history, bot-reason breakdown, flag as bot/threat, delete entries
• Settings — excluded IP management, bot IP management, included/excluded path patterns, automated bot identification, bulk delete bots/threats/visitors, CSV export
• Security — every action endpoint requires authentication (when AuthUserID is configured), POST, and an X-Requested-With: XMLHttpRequest header; nosniff/no-store are set centrally

Usage

import (
    "github.com/dracory/statsadmin"
    "github.com/dracory/statsstore"
)

handler, err := statsadmin.New(statsadmin.AdminOptions{
    Store:             store,            // required
    FuncLayout:        myFuncLayout,     // optional; built-in default when nil
    HomeURL:           "/admin",         // required
    BaseURL:           "/admin/stats",   // defaults to "/admin/stats"
    CountryNameByIso2: countryNameByIso2, // optional
    AuthUserID:        func(r *http.Request) string { /* ... */ }, // optional
    FlashError:        func(w, r, msg, url string, delay int) string { /* ... */ }, // optional
})

http.Handle("/admin/stats", handler)

FuncLayout wraps each dashboard page in your application's chrome:

func myFuncLayout(w http.ResponseWriter, r *http.Request, title, body string, options statsadmin.LayoutOptions) string {
    // options.Styles / StyleURLs / Scripts / ScriptURLs carry per-page assets
    return "<html>..." + body + "...</html>"
}

Controllers

Controller	Query param	Description
Dashboard	controller=dashboard (default)	Overview stats and top-N breakdowns
Visitors	controller=visitors	Paginated, filterable visitor list
Sessions	controller=sessions	Sessions grouped by IP
Settings	controller=settings	Excluded/included paths, IPs, bots, stats
IP Details	controller=ip-details&ip=X	Per-IP details and actions

Example

A complete runnable demo with seeded data lives in example/:

go run ./example
# open http://localhost:8080

Screenshots

Dashboard

Visitors

Sessions

Settings

IP Details

Documentation

Overview

Package statsadmin provides a self-hosted visitor analytics admin dashboard.

It is a self-contained, reusable library package: consumers inject a statsstore.StoreInterface and optional callbacks via statsadmin.New(statsadmin.AdminOptions{...}), and get the full dashboard for free. Rendering goes through FuncLayout so the host application can wrap the dashboard in its own chrome (branding, menus, theme).

The package follows the folder-per-controller pattern: each controller lives in its own subfolder and renders via the shared layout.

Index

• func Handler(opts shared.ControllerOptions, w http.ResponseWriter, r *http.Request)
• type AdminInterface
  • func New(opts AdminOptions) (AdminInterface, error)
• type AdminOptions
• type LayoutOptions

Functions

func Handler

func Handler(opts shared.ControllerOptions, w http.ResponseWriter, r *http.Request)

Handler dispatches the request to the matching controller based on the "controller" query parameter. It writes the response directly to the ResponseWriter.

Types

type AdminInterface

type AdminInterface interface {
	http.Handler
	// Handle processes a stats admin request (alias for ServeHTTP).
	Handle(w http.ResponseWriter, r *http.Request)
}

AdminInterface defines the entry point for the stats admin. It satisfies http.Handler and also exposes the Handle method used by rtr-style routers.

func New

func New(opts AdminOptions) (AdminInterface, error)

New creates a new stats admin instance. It validates required fields and returns an AdminInterface that dispatches to the appropriate controller based on the "controller" query parameter.

type AdminOptions

type AdminOptions struct {
	// Store is the statsstore instance used for all visitor queries. Required.
	Store statsstore.StoreInterface

	// FuncLayout renders an admin page inside the host application's layout
	// (branding, menus, theme). When nil, a default bare-bones HTML page is
	// used (Bootstrap + Vue CDN).
	FuncLayout func(w http.ResponseWriter, r *http.Request, title string, body string, options LayoutOptions) string

	// HomeURL is the URL for the admin home page (e.g. "/admin"). Required.
	HomeURL string

	// WebsiteUrl is the public site URL.
	WebsiteUrl string

	// BaseURL is the base URL for the stats admin (e.g. "/admin/stats").
	// Defaults to "/admin/stats" when empty.
	BaseURL string

	// CountryNameByIso2 maps an ISO2 code to a human-readable country name.
	// Optional; when nil, raw ISO2 codes are displayed.
	CountryNameByIso2 func(iso2Code string) (string, error)

	// AuthUserID returns the authenticated user ID from the request, or ""
	// when unauthenticated. When nil, auth checks are skipped.
	AuthUserID func(r *http.Request) string

	// FlashError renders a flash error message and returns the redirect
	// response body. When nil, controllers fall back to http.Redirect.
	FlashError func(w http.ResponseWriter, r *http.Request, message string, redirectURL string, delaySeconds int) string

	// Logger is used for internal logging. Defaults to slog.Default().
	Logger *slog.Logger
}

AdminOptions contains all dependencies and configuration for the admin dashboard.

type LayoutOptions

type LayoutOptions = struct {
	Styles     []string
	StyleURLs  []string
	Scripts    []string
	ScriptURLs []string
}

LayoutOptions is the anonymous struct passed to FuncLayout, matching the convention used by shopadmin/blogadmin so consumers can reuse the same layout function across dracory admin packages.