api

package

v1.6.6 Latest Latest Go to latest Published: May 7, 2026 License: MIT Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/semihalev/sdns

Links

README ¶

HTTP API

You can manage all blocks with basic HTTP API functions.

All blocklist mutations (single and bulk) take effect immediately and persist asynchronously: the in-memory state is updated under a short-held lock, and the on-disk local blocklist file is rewritten outside the lock via a temp-file + atomic rename. DNS queries are not paused while a write lands, even during a multi-thousand-entry bulk import.

Authentication

API bearer token can be set on sdns config. If the token set, Authorization header should be send on API requests.

Example Header

Authorization: Bearer my_very_long_token

Actions

GET /api/v1/block/set/:key

It is used to create a new block.

request

curl http://localhost:8080/api/v1/block/set/domain.com

response

{"success":true}

GET /api/v1/block/get/:key

Used to request an existing block

request

curl http://localhost:8080/api/v1/block/get/domain.com

response

{"success":true}

or

{"error":"domain.com not found"}

GET /api/v1/block/exists/:key

It queries whether it has a block.

request

curl http://localhost:8080/api/v1/block/exists/domain.com

response

{"success":true}

GET /api/v1/block/remove/:key

Deletes the block.

request

curl http://localhost:8080/api/v1/block/remove/domain.com

response

{"success":true}

POST /api/v1/block/set/batch

Bulk-add multiple block entries in a single call. The whole batch is applied as one map mutation and one disk write, so DNS queries are not paused while a large import lands. Wildcard entries are written as *.example.com (canonical FQDN), exactly like the single-key form.

The request body is JSON, capped at 8 MiB. Unknown fields are rejected. Whitelisted keys count toward skipped, not added.

request

curl -X POST http://localhost:8080/api/v1/block/set/batch
-H 'Content-Type: application/json'
-d '{"keys":["domain.com","*.evil.example","tracker.test"]}'

response

{"requested":3,"added":3,"skipped":0}

POST /api/v1/block/remove/batch

Bulk-remove multiple block entries in a single call. Same one-lock / one-write semantics as the set batch above. Entries that aren't present count toward missing, not removed.

request

curl -X POST http://localhost:8080/api/v1/block/remove/batch
-H 'Content-Type: application/json'
-d '{"keys":["domain.com","*.evil.example","never-existed.test"]}'

response

{"requested":3,"removed":2,"missing":1}

GET /api/v1/purge/domain/type

Purge a cached query.

request

curl http://localhost:8080/api/v1/purge/example.com/MX

response

{"success":true}

GET /metrics

Export the prometheus metrics.

Documentation ¶

Overview ¶

Index ¶

type API
- func New(cfg *config.Config) *API
- func (a *API) Run(ctx context.Context)
type Context
- func (ctx *Context) JSON(code int, data any)
- func (ctx *Context) Param(key string) string
type Group
type Handler
type Json
type Param
type Params
type Router
- func NewRouter() *Router
type Tree
- func (tree *Tree) Add(path string, data dataType)
- func (tree *Tree) Lookup(ctx *Context)

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type API ¶

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

API type.

func New ¶

func New(cfg *config.Config) *API

New return new api.

func (*API) Run ¶

func (a *API) Run(ctx context.Context)

(*API).Run run API server.

type Context ¶ added in v1.3.2

type Context struct {
	Request *http.Request
	Writer  http.ResponseWriter
	Handler Handler
	Params  *Params
}

func (*Context) JSON ¶ added in v1.3.2

func (ctx *Context) JSON(code int, data any)

func (*Context) Param ¶ added in v1.3.2

func (ctx *Context) Param(key string) string

type Group ¶ added in v1.3.2

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

Group represents a group of routes with a common prefix.

func (*Group) GET ¶ added in v1.3.2

func (g *Group) GET(path string, handle Handler)

func (*Group) Handle ¶ added in v1.3.2

func (g *Group) Handle(method, path string, handle Handler)

func (*Group) POST ¶ added in v1.3.2

func (g *Group) POST(path string, handle Handler)

type Handler ¶ added in v1.3.2

type Handler func(ctx *Context)

type Json ¶ added in v1.3.2

type Json map[string]any

type Param ¶ added in v1.3.2

type Param struct {
	Key   string
	Value string
}

type Params ¶ added in v1.3.2

type Params []Param

type Router ¶ added in v1.3.2

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

Router is a high-performance HTTP request router.

func NewRouter ¶ added in v1.3.2

func NewRouter() *Router

func (*Router) GET ¶ added in v1.3.2

func (rt *Router) GET(path string, handle Handler)

func (*Router) Group ¶ added in v1.3.2

func (rt *Router) Group(rp string) *Group

func (*Router) Handle ¶ added in v1.3.2

func (rt *Router) Handle(method, path string, handle Handler)

func (*Router) POST ¶ added in v1.3.2

func (rt *Router) POST(path string, handle Handler)

func (*Router) ServeHTTP ¶ added in v1.3.2

func (rt *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Tree ¶ added in v1.3.2

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

Tree represents a radix tree.

func (*Tree) Add ¶ added in v1.3.2

func (tree *Tree) Add(path string, data dataType)

(*Tree).Add add adds a new element to the tree.

func (*Tree) Lookup ¶ added in v1.3.2

func (tree *Tree) Lookup(ctx *Context)

(*Tree).Lookup lookup finds the data for the request path and assigns it to ctx.Handler, if available.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL