knot

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 10 Imported by: 0

README

Knot backend — the embeddable engine

Go Reference

Knot's backend as an embeddable Go component. A host application brings its own Fiber app and its own GORM database connection, and delegates one concern to the engine: API-documentation management — groups, APIs and parameter trees over REST, plus multi-format export (HTML, Knot JSON, OpenAPI, Postman) and import (Knot JSON, Postman Collection v2.x, OpenAPI 3.x).

The whole integration is three calls:

engine, err := knot.New(knot.Config{DB: db}) // validates + migrates
engine.Mount(app)                            // routes under /api
payload, filename, err := engine.Export(ids, "html", "en")

Knot's own knot-server and knot CLI are thin hosts over this engine (cmd/server and cmd/cli in this module): what they do with Fiber, GORM and the process, an embedding application can do too.

Version status: the module is v0 — the engine API is allowed to change between releases until the first hosts have stabilized it. Pin the version in your go.mod and expect possible breakage until v1.

Installation

go get github.com/ProjAnvil/knot/backend@v0.1.0
import knot "github.com/ProjAnvil/knot/backend"

The package is named knot but lives at the module root (the import path ends in backend), so the explicit alias keeps references reading knot.New / knot.Config. Requires Go 1.25.5+ and any GORM driver you choose (SQLite, PostgreSQL, MySQL — the host opens the connection, not the engine).

The engine depends on the models module (v1.1+) for its data types; for example Knot.Import returns *models.ImportResult from there.

Example: Knot inside a host application

A complete host ("Sentia") that owns its database, mounts the engine's routes at /knot/api, imports a Knot JSON backup directly, and exports HTML:

package main

import (
	"errors"
	"fmt"
	"log"
	"os"

	knot "github.com/ProjAnvil/knot/backend"
	"github.com/glebarez/sqlite"
	"github.com/gofiber/fiber/v2"
	"gorm.io/gorm"
)

func main() {
	// Sentia owns its database and its HTTP app; Knot is a guest in both.
	db, err := gorm.Open(sqlite.Open("sentia.db"), &gorm.Config{})
	if err != nil {
		log.Fatal(err)
	}

	// New validates the config, installs the table prefix and runs the
	// engine's only DDL — AutoMigrate of knot_groups / knot_apis /
	// knot_parameters — leaving Sentia's own tables alone.
	engine, err := knot.New(knot.Config{
		DB:          db,
		APIPrefix:   "/knot/api", // "" means the default "/api"
		TablePrefix: "knot_",     // "" keeps the bare table names
	})
	if err != nil {
		log.Fatal(err)
	}
	defer engine.Close() // no-op: the DB connection belongs to Sentia

	// Mount registers every engine route under /knot/api on Sentia's own
	// Fiber app. It is idempotent per app — mounting defensively is safe.
	app := fiber.New()
	engine.Mount(app)

	// Service methods are direct calls; no HTTP round-trip needed.
	data, err := os.ReadFile("backup.knot.json")
	if err != nil {
		log.Fatal(err)
	}

	preview, err := engine.Import(data, true) // dry run: resolve only
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("dry run: %d group(s) created, %d API(s) imported\n",
		preview.GroupsCreated, preview.APIsImported)

	if _, err := engine.Import(data, false); err != nil {
		if errors.Is(err, knot.ErrImportParse) {
			log.Fatal("backup.knot.json is not a parseable Knot document")
		}
		log.Fatal(err)
	}

	// The prefixed tables are ordinary tables in Sentia's database.
	var ids []uint
	db.Table("knot_apis").Pluck("id", &ids)

	payload, filename, err := engine.Export(ids, "html", "en")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s: %d bytes\n", filename, len(payload))

	// Sentia serves the mounted routes next to its own.
	log.Fatal(app.Listen(":3000"))
}

After New + Mount: the three knot_* tables live in Sentia's database next to its own schema, the engine's routes answer under /knot/api, and Sentia's tables, routes and listener stay entirely under its control.

Host contract

Config
type Config struct {
	DB          *gorm.DB // required — the host's own connection
	APIPrefix   string   // "" → "/api" (DefaultAPIPrefix)
	TablePrefix string   // "" → bare table names (see Table prefix)
}
New
func New(cfg Config) (*Knot, error)
  • DB must be non-nil; anything else fails before touching the database.
  • A non-empty TablePrefix is installed via models.SetTablePrefix before migration. An empty one leaves any prefix the host already set untouched — New never clobbers it.
  • Runs the canonical gormbind.AutoMigrate — the only DDL the engine ever executes (see Ownership rules).
  • Every failure is wrapped with the failing step (e.g. knot: auto-migrate failed: ...).
Mount
func (k *Knot) Mount(app *fiber.App)

Registers all engine routes on the host's app under Config.APIPrefix (default /api). Mount is idempotent per app: mounting the same app twice is a no-op, so hosts can mount defensively, while mounting additional apps registers the full route set on each. It registers nothing else — static file serving, health checks and middleware stay with the host (the standalone server registers its own /api/health before mounting).

Mounted routes:

GET    {prefix}/groups                        list groups
GET    {prefix}/groups/with-apis              groups incl. their APIs
POST   {prefix}/groups                        create group
POST   {prefix}/groups/orders                 reorder groups
PATCH  {prefix}/groups/:id                    update group
DELETE {prefix}/groups/:id                    delete group
GET    {prefix}/apis                          list APIs (paginated, searchable)
GET    {prefix}/apis/:id                      get one API
GET    {prefix}/apis/group/:groupId           APIs of one group
POST   {prefix}/apis                          create API
PATCH  {prefix}/apis/:id                      update API
PATCH  {prefix}/apis/:id/note                 update API note
POST   {prefix}/apis/orders                   reorder APIs
POST   {prefix}/apis/:id/duplicate            duplicate API
DELETE {prefix}/apis/:id                      delete API
PUT    {prefix}/apis/:id/parameters           replace parameter tree
POST   {prefix}/apis/:id/parameters/from-json replace parameters from JSON
POST   {prefix}/export                        export (HTML/JSON/OpenAPI/Postman)
POST   {prefix}/import                        import (auto-detected format)
POST   {prefix}/mcp-tools                     MCP tools endpoint

Responses use the Knot envelope — {"success":true,"data":...} on success, {"success":false,"error":"..."} on failure.

GET {prefix}/apis is a flat, paginated listing for search UIs, ordered by the parent group's position, then API order. Query parameters: page (default 1), pageSize (default 50, clamped to 1..100), keyword (case-insensitive substring match on API name or endpoint), groupId (exact) and method (exact, upper-cased before matching). The data payload is {"items":[...],"total":N,"page":N,"pageSize":N}; non-numeric page, pageSize or groupId values fail with a 400.

Export
func (k *Knot) Export(apiIDs []uint, format string, locale string) ([]byte, string, error)

Renders the selected APIs and returns the payload bytes plus the download filename, byte-identical to the HTTP export handler (both are stamped with the current time at second granularity). format "" and "html" produce the standalone HTML document; "json", "openapi" and "postman" produce the respective JSON documents; anything else fails with ErrUnsupportedFormat. locale selects the HTML document language and defaults to "zh" when empty. An empty apiIDs fails with ErrNoAPIIDs.

Two different "format" notions are at play: the format argument above is a request value — "", html, json, openapi or postman — while the Knot JSON document produced by json carries "format":"knot" in its envelope (models.WireFormat, the v1 wire-format identifier). "knot" is not a valid request value.

Import
func (k *Knot) Import(data []byte, dryRun bool) (*models.ImportResult, error)

Detects the document's format (Knot JSON, Postman Collection v2.x, OpenAPI 3.x), parses it, and applies the whole plan in one transaction. With dryRun=true the identical resolution logic runs but nothing is written; the returned counts are what a real run would produce. Imported groups whose name matches an existing group merge into it, otherwise new groups are created. The result reports format, groupsCreated, groupsMerged, apisImported, parametersImported and warnings (field names as JSON-encoded by the import endpoint).

Close
func (k *Knot) Close() error

A documented no-op. The engine holds no resources of its own — the database connection belongs to the host — so Close exists only to be deferred symmetrically with New.

Errors

The service methods report failures as sentinel errors, listed here exactly as defined. Match them with errors.Is; wrapped detail is preserved, so err.Error() stays log-worthy while the mapping stays stable. The suggested HTTP analog mirrors the standalone server's handlers:

Sentinel Meaning HTTP analog
ErrUnsupportedFormat export format or import document not recognized 415
ErrNoAPIIDs Export called with an empty apiIDs 400
ErrExportFailed database or encoding failure during export 500
ErrImportParse a detected import document failed to parse 400
ErrImportApply failure while persisting an import plan 500

Ownership rules

  • The database connection belongs to the host. The engine never closes it — Close is a no-op. Open, share and close the *gorm.DB like any other part of the host.
  • The engine's only DDL is the AutoMigrate inside New. It creates or extends the (optionally prefixed) groups, apis and parameters tables and nothing else — no drops, no renames, no other schema objects.
  • One engine instance per process. The table prefix is process-wide state (models.TablePrefix); a second engine instance in the same process would silently share it. Mount is idempotent per app by design — remounting the same app is a no-op, and each additional app gets its own route registration.
  • SetTablePrefix runs once, before the first database use. Config.TablePrefix does this for you (installed before migration, only when non-empty). Hosts that call models.SetTablePrefix themselves should leave Config.TablePrefix empty — GORM caches parsed table names per *gorm.DB, so a later change has no effect on an open database, and existing tables are never renamed.

Table prefix

Knot's table names are generic — groups, apis, parameters — which is fine for a dedicated database but a collision risk in a database shared with the host's own schema. Config.TablePrefix namespaces them:

TablePrefix Physical tables
"" (default) groups, apis, parameters
"knot_" knot_groups, knot_apis, knot_parameters
  • The default empty prefix is a compatibility guarantee: it produces exactly the standalone product's physical schema, so pointing the engine at an existing Knot database (or the models module's v1.0 layout) just works.
  • The prefix is process-global — set it through Config before migration, once (see Ownership rules).
  • The host's own tables are untouched; the embedded-host smoke test in CI (backend job) asserts exactly this coexistence.

Versioning

This module is the backend/ directory of ProjAnvil/knot, versioned independently with backend/v* git tags (the same scheme as the models module). The current line is v0: the engine API may change between releases until host feedback stabilizes it; v1 brings full semver guarantees.

Standalone binaries

cmd/server (knot-server) and cmd/cli (knot) in this module are reference hosts: they open the database from the configuration file, register their own health endpoint and static frontend, then New + Mount the engine. Build them with make build from this directory, or see the repository README for the full development workflow.

License

MIT — same as the repository (LICENSE).

Documentation

Overview

Package knot embeds the Knot API-documentation engine into any Go host.

A host opens its own *gorm.DB, constructs the engine with New, optionally mounts the HTTP routes onto its Fiber app with Mount, and otherwise calls the service methods (Export, Import) directly. The engine owns no global state of its own beyond the process-wide models.TablePrefix that Config.TablePrefix installs (only when non-empty, so a host-set prefix is never clobbered).

Ownership rules: the database connection belongs to the host (Close is a documented no-op); Mount only registers routes — the host keeps ownership of static file serving, health endpoints and any other middleware.

Index

Constants

View Source
const DefaultAPIPrefix = "/api"

DefaultAPIPrefix is the route prefix used when Config.APIPrefix is empty, identical to the prefix the standalone Knot server serves.

Variables

View Source
var (
	// ErrUnsupportedFormat reports an export format or import document the
	// engine does not recognize.
	ErrUnsupportedFormat = errors.New("knot: unsupported format")
	// ErrNoAPIIDs reports an Export call with an empty apiIDs slice.
	ErrNoAPIIDs = errors.New("knot: no API IDs provided")
	// ErrExportFailed wraps database or encoding failures during Export.
	ErrExportFailed = errors.New("knot: export failed")
	// ErrImportParse wraps failures to parse a detected import document.
	ErrImportParse = errors.New("knot: failed to parse import document")
	// ErrImportApply wraps failures to persist an import plan.
	ErrImportApply = errors.New("knot: failed to apply import document")
)

Sentinel errors reported by the service methods. Hosts map them to HTTP statuses with errors.Is: ErrUnsupportedFormat is the 415 case (mirroring the import handler), ErrNoAPIIDs and ErrImportParse are user-input (400) cases, and ErrExportFailed and ErrImportApply are internal (500) cases. Non-sentinel detail is preserved by wrapping, so err.Error() stays log-worthy while errors.Is keeps the mapping stable.

Functions

This section is empty.

Types

type Config

type Config struct {
	DB          *gorm.DB
	APIPrefix   string
	TablePrefix string
}

Config configures an engine instance. DB is required. APIPrefix defaults to DefaultAPIPrefix when empty. TablePrefix, when non-empty, is installed as the process-wide models.TablePrefix before migration so every engine table is namespaced (e.g. "knot_" → knot_groups); when empty, any prefix the host already set is left untouched.

type Knot

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

Knot is an instance of the embeddable engine. Construct with New.

func New

func New(cfg Config) (*Knot, error)

New validates the configuration, installs the table prefix (only when configured — a host-set prefix is never clobbered), runs the canonical AutoMigrate via models/gormbind, and returns a ready engine. All errors are wrapped with the failing step.

func (*Knot) Close

func (k *Knot) Close() error

Close releases engine resources. The engine owns none — the database connection belongs to the host — so Close is a documented no-op that hosts may defer symmetrically with New.

func (*Knot) Export

func (k *Knot) Export(apiIDs []uint, format string, locale string) ([]byte, string, error)

Export renders the selected APIs in the given format and returns the payload and the download filename, byte-identical to the HTTP export handler: format "" and "html" produce the HTML document, "json", "openapi" and "postman" the respective JSON documents. locale selects the HTML language and defaults to "zh" when empty. The payload and filename are stamped with the current time at second granularity, exactly like the handler; hosts pick the Content-Type from the format the same way the export handler does.

func (*Knot) Import

func (k *Knot) Import(data []byte, dryRun bool) (*models.ImportResult, error)

Import detects the format of the given document bytes (Knot JSON, Postman Collection v2.x, OpenAPI 3.x), parses it and applies it in one transaction. With dryRun=true the same resolution logic runs but nothing is written and the returned counts are the ones a real run would produce. Error mapping mirrors the HTTP import handler: an undetectable or unsupported document wraps ErrUnsupportedFormat (the 415 case), a parse failure wraps ErrImportParse, and a persistence failure wraps ErrImportApply.

func (*Knot) Mount

func (k *Knot) Mount(app *fiber.App)

Mount registers the engine's HTTP routes on the app under Config.APIPrefix (default "/api"). Mount is idempotent per app: mounting the same app a second time is a no-op — so hosts can mount defensively — while mounting the same engine on several distinct apps registers the full route set on each. Static file serving, health checks and host routes are not touched — those stay with the host.

Directories

Path Synopsis
cmd
cli command
server command
internal
cli
pkg

Jump to

Keyboard shortcuts

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