forge

type AIDocSummary ¶

type AIDocSummary interface{ AISummary() string }

AIDocSummary is implemented by content types that provide a concise, human-readable summary optimised for AI consumption. The summary is used in /llms.txt entries and the summary: field of AIDoc output.

When a content type implements neither AIDocSummary nor Markdownable, Forge falls back to Head.Description.

type AIFeature ¶

type AIFeature int

AIFeature selects which AI indexing endpoints are enabled for a module. Pass one or more AIFeature constants to AIIndex.

const (
	// LLMsTxt enables the /llms.txt compact content index for the module.
	// Only Published items appear. Regenerated on every publish event.
	LLMsTxt AIFeature = 1

	// LLMsTxtFull enables the /llms-full.txt full markdown corpus for the module.
	// Each Published item is rendered as a full document with a header.
	// Only Published items appear. Regenerated on every publish event.
	LLMsTxtFull AIFeature = 2

	// AIDoc enables per-item /{prefix}/{slug}.aidoc endpoints. Each endpoint
	// returns the item in token-efficient AIDoc format (text/plain).
	// Only Published items are served; non-Published items return 404.
	AIDoc AIFeature = 3
)

type Alternate ¶

type Alternate struct {
	Locale string // BCP 47 language tag, e.g. "en-GB"
	URL    string // absolute URL for this locale
}

Alternate is an hreflang entry for internationalised pages. Reserved for v2 — Forge always generates an empty Alternates slice in v1.

type App ¶

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

App is the central registry for a Forge application. It couples the HTTP router, global middleware, and all content modules into a single value.

Create an App with New, wire in modules with App.Content, add global middleware with App.Use, then serve with App.Run or App.Handler.

Optional cross-cutting features are configured directly on the App:

• App.SEO — robots.txt, sitemap index, AI-crawler policy
• App.Cookies + App.CookiesManifestAuth — typed cookie compliance manifest
• App.Redirect + App.RedirectStore + App.RedirectManifestAuth — redirect rules

App is not safe for concurrent configuration: set it up in main before calling Run or Handler, then treat it as read-only.

func New(cfg Config) *App

func (a *App) Config() Config

func (a *App) Content(v any, opts ...Option)

posts := forge.NewModule[*Post](&Post{}, forge.Repo(repo), forge.At("/posts"))
app.Content(posts)

func (a *App) Cookies(decls ...Cookie)

app.Cookies(
    forge.Cookie{Name: "session", Category: forge.Necessary, ...},
    forge.Cookie{Name: "prefs",   Category: forge.Preferences, ...},
)

func (a *App) CookiesManifestAuth(auth AuthFunc)

app.CookiesManifestAuth(forge.BearerHMAC(secret, forge.Editor))

func (a *App) Handle(pattern string, handler http.Handler)

app.Handle("GET /healthz", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
}))

func (a *App) Handler() http.Handler

srv := &http.Server{Handler: app.Handler()}

func (a *App) Health()

app.Health()
// GET /_health → {"status":"ok","forge":"1.1.6","forge_mcp":"1.0.5"}

func (a *App) MCPModules() []MCPModule

func (a *App) MustParseTemplate(path string) *template.Template

app.Partials("templates/partials")
homeTpl := app.MustParseTemplate("templates/home.html")
app.Handle("GET /", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    homeTpl.Execute(w, data)
}))

func (a *App) Nav(items ...NavItem)

func (a *App) NavTree() *NavTree

func (a *App) Partials(dir string) *App

{{template "nav" .}}

app.Partials("templates/partials")

app := New(MustConfig(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
}))

// Any *.html file in templates/partials is injected into every module
// template set and into templates parsed via MustParseTemplate.
app.Partials("templates/partials")

_ = app.Handler()

func (a *App) Redirect(from, to string, code RedirectCode)

app.Redirect("/old-path", "/new-path", forge.Permanent)

app.Redirect("/removed", "", forge.Gone)

func (a *App) RedirectManifestAuth(auth AuthFunc)

app.RedirectManifestAuth(forge.BearerHMAC(secret, forge.Editor))

func (a *App) RedirectStore() *RedirectStore

if err := app.RedirectStore().Load(ctx, db); err != nil {
    log.Fatal(err)
}

func (a *App) Run(addr string) error

if err := app.Run(":8080"); err != nil {
    log.Fatal(err)
}

func (a *App) SEO(opts ...SEOOption)

app.SEO(&forge.RobotsConfig{AIScraper: forge.AskFirst, Sitemaps: true})

func (a *App) Secret() []byte

func (a *App) TokenStore() *TokenStore

func (a *App) Use(mws ...func(http.Handler) http.Handler)

app.Use(forge.RequestLogger(), forge.Recoverer(), forge.SecurityHeaders())

type AppSchema ¶

type AppSchema struct {
	// Type is the JSON-LD @type, e.g. "Organization" or "WebSite".
	Type string

	// Name is the human-readable name of the organisation or site.
	Name string

	// URL is the canonical URL of the organisation or site's home page.
	URL string

	// Logo is the absolute URL of the organisation's logo image.
	Logo string
}

AppSchema registers app-level JSON-LD structured data emitted in every page's <head> by forge:head. Use it to declare site-wide Organisation or WebSite metadata once rather than per content type.

Apply via App.SEO:

app.SEO(&forge.AppSchema{
    Type: "Organization",
    Name: "Acme Corp",
    URL:  "https://acme.com",
    Logo: "https://acme.com/logo.png",
})

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.SEO(&AppSchema{
	Type: "Organization",
	Name: "Acme Corp",
	URL:  "https://example.com",
	Logo: "https://example.com/logo.png",
})
_ = app.Handler()

type AuthFunc ¶

type AuthFunc interface {
	// contains filtered or unexported methods
}

AuthFunc authenticates an incoming HTTP request and returns the identified User and whether authentication succeeded. Use BearerHMAC, CookieSession, BasicAuth, or AnyAuth to obtain an AuthFunc. Implement this interface to provide a custom authentication scheme.

The unexported authenticate method is intentional: it prevents accidental direct calls and allows future additions to the interface without breaking existing implementations (consistent with Option and Signal).

func AnyAuth(fns ...AuthFunc) AuthFunc

func BasicAuth(username, password string) AuthFunc

func BearerHMAC(secret string) AuthFunc

func CookieSession(name, secret string, opts ...Option) AuthFunc

type Breadcrumb ¶

type Breadcrumb struct {
	Label string // human-readable label
	URL   string // root-relative or absolute URL
}

Breadcrumb is a single step in a breadcrumb trail. Build slices using the Crumb constructor and the Crumbs helper.

func Crumb(label, url string) Breadcrumb

forge.Crumbs(
    forge.Crumb("Home",  "/"),
    forge.Crumb("Posts", "/posts"),
    forge.Crumb(p.Title, "/posts/"+p.Slug),
)

func Crumbs(crumbs ...Breadcrumb) []Breadcrumb

type CacheStore ¶

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

CacheStore is a thread-safe LRU cache of HTTP responses used by InMemoryCache and by Module for signal-triggered invalidation. Use NewCacheStore to create one.

func NewCacheStore(ttl time.Duration, max int) *CacheStore

func (c *CacheStore) Flush()

func (c *CacheStore) Sweep()

type ChangeFreq ¶

type ChangeFreq string

ChangeFreq is the value of a sitemap <changefreq> element, indicating how frequently the page content is likely to change.

const (
	// Always signals the URL changes with every access. Use for live data.
	Always ChangeFreq = "always"

	// Hourly signals the URL is updated approximately once per hour.
	Hourly ChangeFreq = "hourly"

	// Daily signals the URL is updated approximately once per day.
	Daily ChangeFreq = "daily"

	// Weekly signals the URL is updated approximately once per week.
	// This is the default when [SitemapConfig.ChangeFreq] is empty.
	Weekly ChangeFreq = "weekly"

	// Monthly signals the URL is updated approximately once per month.
	Monthly ChangeFreq = "monthly"

	// Yearly signals the URL is updated approximately once per year.
	Yearly ChangeFreq = "yearly"

	// Never signals the URL is permanently archived and will not change.
	Never ChangeFreq = "never"
)

type Config ¶

type Config struct {
	// BaseURL is the canonical URL of the site, e.g. "https://example.com"
	// (no trailing slash). Required.
	BaseURL string

	// Secret is the HMAC signing key used by [BearerHMAC], [CookieSession], and
	// [SignToken]. It must be at least 16 bytes. Required.
	//
	// When Auth is nil, Secret is used to validate Bearer tokens automatically
	// via [BearerHMAC]. Set [Config.Auth] to override.
	Secret []byte

	// Auth is the [AuthFunc] used to authenticate requests. When nil, Forge
	// defaults to [BearerHMAC] using [Config.Secret]. Set this explicitly to
	// use [CookieSession], [AnyAuth], or a custom [AuthFunc].
	//
	// Example — cookie sessions instead of bearer tokens:
	//
	//	Auth: forge.CookieSession("session", secret)
	//
	// Example — both bearer tokens and cookie sessions:
	//
	//	Auth: forge.AnyAuth(
	//	    forge.BearerHMAC(secret),
	//	    forge.CookieSession("session", secret),
	//	)
	Auth AuthFunc

	// TokenStore enables database-backed named bearer token management. When
	// set, [VerifyBearerToken] checks the forge_tokens table to validate that
	// a token has not been revoked. The forge_tokens table must exist before
	// the application starts; see [TokenStore] for the required DDL.
	// Optional — leave nil to use HMAC-only token validation.
	TokenStore *TokenStore

	// Version is the application version string. It is an optional field for
	// application authors who want to track their own release version; forge
	// itself does not use this field in any built-in endpoint.
	Version string

	// DB is the database connection used by content modules.
	// It accepts *sql.DB, *sql.Tx, or any value that satisfies [DB].
	// Optional — leave nil to use in-memory repositories only.
	DB DB

	// HTTPS forces an HTTP→HTTPS redirect for all plain-HTTP requests when
	// true. The App handler checks r.TLS and the X-Forwarded-Proto header so
	// this works correctly behind a reverse proxy. Optional.
	HTTPS bool

	// ReadTimeout is the maximum time to read the full request, including the
	// body. Defaults to 5 s. Optional.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum time to write the full response. Defaults to
	// 10 s. Optional.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum keep-alive idle time between requests.
	// Defaults to 120 s. Optional.
	IdleTimeout time.Duration

	// NavMode selects how the application's navigation tree is populated.
	// Use [NavModeDB] to persist navigation items in the forge_nav database
	// table (requires [Config.DB]; panics at startup if DB is nil).
	// Use [NavModeCode] to supply items directly via [App.Nav].
	// The zero value disables navigation entirely. Optional.
	NavMode NavMode

	// AppSchema sets the app-level JSON-LD structured data block emitted on
	// every page as a <script type="application/ld+json"> element. When set
	// here, it is applied automatically at startup; an explicit [App.SEO] call
	// with an [AppSchema] takes precedence. This field is also populated when
	// a forge.config file contains the org_name or org_type keys. Optional.
	AppSchema *AppSchema

	// OGDefaults sets the app-level Open Graph and Twitter Card fallback values
	// applied to every page. When set here, it is applied automatically at
	// startup; an explicit [App.SEO] call with an [OGDefaults] takes
	// precedence. Also populated from forge.config og_image and twitter_site
	// keys. Optional.
	OGDefaults *OGDefaults

	// MediaPath is the filesystem directory where forge-media stores uploaded
	// files. Defaults to "./media" when zero. Optional — only read by
	// forge-media; ignored by forge core.
	MediaPath string

	// MediaMaxSize is the maximum permitted upload size in bytes. Defaults to
	// 5242880 (5 MB) when zero. Optional — only read by forge-media; ignored
	// by forge core.
	MediaMaxSize int64
}

Config holds the application-wide configuration passed to New.

BaseURL and Secret are required; all other fields are optional.

Timeouts default to 5 s (read), 10 s (write), and 120 s (idle) when left as zero. Set them explicitly to override.

func MustConfig(cfg Config) Config

app := forge.New(forge.MustConfig(forge.Config{
    BaseURL: os.Getenv("BASE_URL"),
    Secret:  []byte(os.Getenv("SECRET")),
}))

type Context ¶

type Context interface {
	context.Context

	// User returns the authenticated identity for this request.
	// Returns [GuestUser] (zero value) for unauthenticated requests.
	User() User

	// Locale returns the BCP 47 language tag for this request.
	// Always "en" in v1; i18n support is planned for v2 (Decision 11).
	Locale() string

	// SiteName returns the configured site name. Always "" in v1 until
	// wired in forge.go (Step 11).
	SiteName() string

	// RequestID returns the UUID v7 assigned to this request for
	// end-to-end traceability. Set as X-Request-ID on the response.
	RequestID() string

	// Request returns the underlying *http.Request.
	Request() *http.Request

	// Response returns the http.ResponseWriter for this request.
	Response() http.ResponseWriter
}

Context is the request-scoped value passed to every Forge hook and handler. It embeds context.Context for full compatibility with stdlib and third-party libraries, while exposing Forge-specific accessors without key-based lookups.

forge.Context is always non-nil — Forge guarantees this before any user code is called. The internal implementation is [contextImpl] (unexported). Use ContextFrom in production and NewTestContext in tests.

func ContextFrom(w http.ResponseWriter, r *http.Request) Context

func NewBackgroundContext(siteName string) Context

func NewContextWithUser(user User) Context

func NewTestContext(user User) Context

type Cookie ¶

type Cookie struct {
	// Name is the cookie name as set on the wire.
	Name string

	// Category classifies the cookie for consent enforcement.
	Category CookieCategory

	// Path scopes the cookie to a URL prefix. Defaults to "/" if empty.
	Path string

	// Domain optionally scopes the cookie to a domain.
	Domain string

	// Secure restricts the cookie to HTTPS connections.
	Secure bool

	// HttpOnly prevents JavaScript from accessing the cookie.
	HttpOnly bool

	// SameSite controls cross-site request behaviour.
	// Defaults to http.SameSiteStrictMode when zero.
	SameSite http.SameSite

	// MaxAge is the cookie lifetime in seconds.
	// 0 = session cookie; negative = delete immediately.
	MaxAge int

	// Purpose is a human-readable description for the compliance manifest.
	Purpose string
}

Cookie declares a typed cookie with its category, attributes, and purpose.

Category determines which set API is legal (Decision 5):

• Necessary: use SetCookie — no consent required
• Preferences, Analytics, Marketing: use SetCookieIfConsented

Purpose is a human-readable description included in the compliance manifest at /.well-known/cookies.json.

type CookieCategory ¶

type CookieCategory string

CookieCategory classifies a cookie by its GDPR consent requirement. The category determines which set API is legal (Decision 5).

const (
	// Necessary cookies are required for the site to function.
	// They do not require user consent and must be set with [SetCookie].
	Necessary CookieCategory = "necessary"

	// Preferences cookies remember user settings (e.g. language, theme).
	// They require consent and must be set with [SetCookieIfConsented].
	Preferences CookieCategory = "preferences"

	// Analytics cookies collect anonymous usage statistics.
	// They require consent and must be set with [SetCookieIfConsented].
	Analytics CookieCategory = "analytics"

	// Marketing cookies track users across sites for advertising purposes.
	// They require consent and must be set with [SetCookieIfConsented].
	Marketing CookieCategory = "marketing"
)

type CrawlerPolicy ¶

type CrawlerPolicy string

CrawlerPolicy controls how AI web crawlers are treated in the generated robots.txt. The zero value is Allow.

const (
	// Allow permits all crawlers, including AI training scrapers.
	// This is the zero-value default.
	Allow CrawlerPolicy = "allow"

	// Disallow blocks all known AI training crawlers by adding individual
	// User-agent / Disallow: / entries for each identified bot.
	Disallow CrawlerPolicy = "disallow"

	// AskFirst blocks known AI training crawlers while permitting AI
	// assistants that respect the robots.txt contract. Recommended for
	// sites that wish to be indexed by AI search but not scraped for
	// training.
	AskFirst CrawlerPolicy = "ask-first"
)

type DB ¶

type DB interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

DB is satisfied by *sql.DB, *sql.Tx, and any pgx adapter such as forgepgx.Wrap(pool). Users pass a concrete implementation to forge.Config — they do not implement DB directly.

type Error ¶

type Error interface {
	error
	// Code returns a machine-readable error identifier (e.g. "not_found").
	Code() string
	// HTTPStatus returns the HTTP status code that should be sent to the client.
	HTTPStatus() int
	// Public returns a message that is safe to expose to API clients.
	Public() string
}

Error is implemented by all Forge errors. Callers should use errors.As to inspect the concrete type — never type-assert directly against a sentinel.

type EventDetails ¶

type EventDetails struct {
	StartDate time.Time
	EndDate   time.Time
	Location  string // venue name
	Address   string // street address or city
}

EventDetails carries the extra fields required for Event rich results.

type EventProvider ¶

type EventProvider interface{ EventDetails() EventDetails }

EventProvider is implemented by content types that supply event structured data.

type FAQEntry ¶

type FAQEntry struct {
	Question string
	Answer   string
}

FAQEntry is a single question-and-answer pair for FAQPage rich results.

type FAQProvider ¶

type FAQProvider interface{ FAQEntries() []FAQEntry }

FAQProvider is implemented by content types that supply FAQ structured data. Return a non-empty slice to enable FAQPage JSON-LD generation via SchemaFor.

type FeedConfig ¶

type FeedConfig struct {
	// Title is the channel title shown in feed readers.
	// Defaults to the capitalised prefix (e.g. "Posts").
	Title string

	// Description is the channel description.
	// Defaults to the site hostname when empty.
	Description string

	// Language is the BCP 47 language code for the feed.
	// Defaults to "en".
	Language string
}

FeedConfig configures the RSS 2.0 feed for a content module. Pass it to Feed to enable feed generation for the module.

All fields are optional. Title defaults to the capitalised module prefix (e.g. "/posts" → "Posts"). Language defaults to "en".

type FeedStore ¶

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

FeedStore holds pre-built RSS item fragments from all Feed-enabled content modules. It is shared across modules via App.Content and provides per-module and aggregate /feed.xml HTTP handlers.

All public methods are safe for concurrent use.

func NewFeedStore(siteName, baseURL string) *FeedStore

func (s *FeedStore) HasFeeds() bool

func (s *FeedStore) IndexHandler() http.Handler

func (s *FeedStore) ModuleHandler(prefix string) http.Handler

func (s *FeedStore) Set(prefix string, cfg FeedConfig, items []rssItem)

type From ¶

type From string

From is the old URL prefix supplied to the Redirects module option. Wrapping in a named type makes call sites self-documenting:

forge.Redirects(forge.From("/posts"), "/articles")

type Head ¶

type Head struct {
	Title       string          // page title; used in <title>, og:title, and JSON-LD
	Description string          // meta description; recommended max 160 characters
	Author      string          // author name; used in <meta name="author"> and JSON-LD
	Published   time.Time       // publication date; zero value omits date tags
	Modified    time.Time       // last-modified date; zero value omits date tags
	Image       Image           // primary image; zero URL omits all image tags
	Type        string          // rich result type (Article, Product, etc.); empty omits JSON-LD
	Canonical   string          // canonical URL; empty omits the canonical tag
	Tags        []string        // content tags; used for article:tag meta and RSS categories
	Breadcrumbs []Breadcrumb    // breadcrumb trail; empty omits BreadcrumbList JSON-LD
	Alternates  []Alternate     // hreflang entries; always empty in v1
	Social      SocialOverrides // per-item social sharing overrides; zero value uses defaults
	NoIndex     bool            // true renders <meta name="robots" content="noindex">
}

Head carries all SEO and social metadata for a content page. Define it on your content type via the Headable interface. Forge uses the Head to populate HTML <head> tags, JSON-LD structured data, sitemaps, RSS feeds, and AI endpoints.

All fields are optional: the zero value is safe and produces a minimal page header.

type HeadAssets ¶

type HeadAssets struct {
	Preconnect  []string    // <link rel="preconnect" href="…">
	Stylesheets []string    // <link rel="stylesheet" href="…">
	Links       []HeadLink  // any <link> element — icons, rel="me", rel="manifest", etc.
	Scripts     []ScriptTag // <script …>
}

HeadAssets is an SEOOption that injects static linked assets — preconnect hints, stylesheets, link elements, and scripts — into the forge:head partial on every page.

Apply it via App.SEO:

app.SEO(&forge.HeadAssets{
    Preconnect:  []string{"https://fonts.googleapis.com"},
    Stylesheets: []string{"https://fonts.googleapis.com/css2?family=Inter&display=swap"},
    Links: []forge.HeadLink{
        {Rel: "icon", Type: "image/png", Sizes: "32x32", Href: "/favicon-32.png"},
        {Rel: "me", Href: "https://mastodon.social/@you"},
    },
    Scripts: []forge.ScriptTag{
        {Src: "/static/app.js", Defer: true},
    },
})

Assets are emitted in order: preconnect → stylesheets → links → scripts.

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.SEO(&HeadAssets{
	Preconnect:  []string{"https://fonts.googleapis.com"},
	Stylesheets: []string{"https://fonts.googleapis.com/css2?family=Inter&display=swap", "/static/app.css"},
	Links: []HeadLink{
		{Rel: "icon", Type: "image/png", Sizes: "32x32", Href: "/favicon-32.png"},
		{Rel: "apple-touch-icon", Href: "/apple-touch-icon.png"},
	},
	Scripts: []ScriptTag{
		{Src: "/static/app.js", Defer: true},
	},
})
_ = app.Handler()

type HeadLink ¶

type HeadLink struct {
	Rel   string // e.g. "icon", "apple-touch-icon", "me", "manifest"
	Type  string // MIME type, e.g. "image/png"; omitted when empty
	Sizes string // e.g. "32x32"; omitted when empty
	Href  string // URL for the href attribute
}

HeadLink declares a single HTML <link> element. Use it for any link relationship: favicons, touch icons, rel="me" profile verification, rel="manifest", or any other rel value. Rel and Href are required; Type and Sizes are optional and omitted when empty.

type Headable ¶

type Headable interface{ Head() Head }

Headable is implemented by content types that provide their own SEO metadata. Module[T] calls Head() automatically when building HTML responses, sitemaps, RSS feeds, and AI endpoints — no HeadFunc option required. HeadFunc takes priority over Headable when both are present.

type HowToProvider ¶

type HowToProvider interface{ HowToSteps() []HowToStep }

HowToProvider is implemented by content types that supply step-by-step structured data for HowTo rich results.

type HowToStep ¶

type HowToStep struct {
	Name string // short label for the step
	Text string // full instruction text
}

HowToStep is a single step in a HowTo or Recipe structured data block.

type Image ¶

type Image struct {
	URL    string // absolute or root-relative
	Alt    string // accessibility and SEO description
	Width  int    // pixels; required for og:image:width
	Height int    // pixels; required for og:image:height
}

Image is a typed image reference. Width and Height are required for optimal Open Graph rendering and Twitter Card display. The zero value (empty URL) renders no image tags — safe to leave unset.

type LLMsEntry ¶

type LLMsEntry struct {
	// Title is the content item's title. Required.
	Title string

	// URL is the canonical URL for this item. Required.
	URL string

	// Summary is a short plain-text description. Optional; omitted when empty.
	Summary string
}

LLMsEntry is a single compact entry in /llms.txt output. Fields map to the llmstxt.org compact format: - [Title](URL): Summary

type LLMsStore ¶

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

LLMsStore holds compact and full content fragments for /llms.txt and /llms-full.txt. Thread-safe. Analogous to SitemapStore.

Created by App.Content when the first module registers with AIIndex. Passed to each module via setAIRegistry.

func NewLLMsStore(siteName string) *LLMsStore

func (s *LLMsStore) CompactHandler() http.Handler

func (s *LLMsStore) FullHandler() http.Handler

func (s *LLMsStore) HasCompact() bool

func (s *LLMsStore) HasFull() bool

func (s *LLMsStore) SetCompact(prefix string, entries []LLMsEntry)

func (s *LLMsStore) SetFull(prefix string, body string)

type LLMsTemplateData ¶

type LLMsTemplateData struct {
	// SiteName is the hostname of the site (e.g. "example.com").
	SiteName string

	// Description is a one-line site description. Empty by default;
	// set manually in custom templates.
	Description string

	// Entries contains all compact entries across all registered modules.
	Entries []LLMsEntry

	// GeneratedAt is the generation date in YYYY-MM-DD format.
	GeneratedAt string

	// ItemCount is the total number of Published items across all modules.
	ItemCount int
}

LLMsTemplateData is the data value passed to custom llms.txt templates. Create templates/llms.txt in your template directory to override the built-in format:

# {{.SiteName}}

> {{.Description}}

## All Content
{{forge_llms_entries .}}

type ListOptions ¶

type ListOptions struct {
	// Page is one-based. Values ≤ 0 are treated as page 1.
	Page int
	// PerPage is the maximum number of items per page.
	// A value of 0 means return all items.
	PerPage int
	// OrderBy is the Go field name to sort by (e.g. "Title").
	// Sorting applies only to exported string fields; other types are ignored.
	OrderBy string
	// Desc reverses the sort order when true.
	Desc bool
	// Status restricts results to items whose Status field matches one of the
	// given values. An empty or nil slice means return all statuses.
	Status []Status
}

ListOptions controls pagination and ordering for FindAll queries.

func (o ListOptions) Offset() int

type MCPField ¶

type MCPField struct {
	Name        string // Go field name
	JSONName    string // lowercase snake_case name used in MCP messages
	Type        string // "string" | "number" | "boolean" | "datetime"
	Format      string // "" when no forge_format tag present; e.g. "markdown", "html"
	Description string // "" when no forge_description tag present; free-text authoring guidance
	Required    bool
	MinLength   int      // 0 = no constraint
	MaxLength   int      // 0 = no constraint
	Enum        []string // nil = no constraint
}

MCPField describes a single field in a content type's MCP schema, derived automatically from the Go struct type and forge: struct tags. Returned by [MCPModule.MCPSchema].

The optional [MCPField.Format] and [MCPField.Description] fields are populated from the forge_format and forge_description struct tags respectively (Decision 27). Both are hints only — Forge performs no validation based on either value.

type MCPMeta ¶

type MCPMeta struct {
	Prefix     string         // URL prefix, e.g. "/posts"
	TypeName   string         // content type name, e.g. "BlogPost"
	Operations []MCPOperation // MCPRead and/or MCPWrite
}

MCPMeta describes the MCP registration of a content module. Returned by [MCPModule.MCPMeta].

type MCPModule ¶

type MCPModule interface {
	// MCPMeta returns the module's MCP registration metadata.
	MCPMeta() MCPMeta
	// MCPSchema returns the field schema derived from the content type's
	// struct tags.
	MCPSchema() []MCPField
	// MCPList returns all items matching the given statuses (all statuses if
	// none are given).
	MCPList(ctx Context, status ...Status) ([]any, error)
	// MCPGet returns the item with the given slug.
	// MCPGet does not filter by lifecycle status — it returns the item
	// regardless of status. Callers are responsible for enforcing lifecycle
	// rules (e.g. forge-mcp checks that the item is Published before
	// including it in a resources/read response).
	MCPGet(ctx Context, slug string) (any, error)
	// MCPCreate creates a new item from the given fields map.
	MCPCreate(ctx Context, fields map[string]any) (any, error)
	// MCPUpdate applies a partial update to the item with the given slug.
	MCPUpdate(ctx Context, slug string, fields map[string]any) (any, error)
	// MCPPublish transitions the item with the given slug to Published.
	MCPPublish(ctx Context, slug string) error
	// MCPSchedule sets the item with the given slug to publish at the given time.
	MCPSchedule(ctx Context, slug string, at time.Time) error
	// MCPArchive transitions the item with the given slug to Archived.
	MCPArchive(ctx Context, slug string) error
	// MCPDelete permanently deletes the item with the given slug.
	MCPDelete(ctx Context, slug string) error
}

MCPModule is implemented by any Module[T] that has been registered with MCP. forge-mcp reads this interface to build MCP resources and tools without accessing Module internals directly.

All methods receive a Context carrying the authenticated user. Callers must construct the Context with the appropriate Role before calling any mutating method — the MCPModule implementation enforces roles and validation identically to the HTTP layer.

type MCPOperation ¶

type MCPOperation string

MCPOperation is an option flag for the MCP function. Only MCPRead and MCPWrite are defined.

const (
	// MCPRead signals that this module should be exposed as a read-only MCP
	// resource. The forge-mcp server will include it in resources/list and
	// resources/read responses. See [MCPModule].
	MCPRead MCPOperation = "read"

	// MCPWrite signals that this module should be exposed as a read+write MCP
	// resource. The forge-mcp server will generate tools for create, update,
	// publish, schedule, archive, and delete operations. See [MCPModule].
	MCPWrite MCPOperation = "write"
)

type Markdownable ¶

type Markdownable interface{ Markdown() string }

Markdownable is implemented by content types that render directly to Markdown. When T implements Markdownable, Module serves text/markdown responses without requiring forge.Templates to be configured. The Markdown body is also used in AIDoc output and /llms-full.txt corpus entries.

type MemoryRepo ¶

type MemoryRepo[T any] struct {
	// contains filtered or unexported fields
}

MemoryRepo is a thread-safe in-memory implementation of Repository. It is intended for unit tests and prototyping — not production use. Fields named ID and Slug are located via cached reflection on first use.

func NewMemoryRepo[T any]() *MemoryRepo[T]

func (r *MemoryRepo[T]) Delete(_ context.Context, id string) error

func (r *MemoryRepo[T]) FindAll(_ context.Context, opts ListOptions) ([]T, error)

func (r *MemoryRepo[T]) FindByID(_ context.Context, id string) (T, error)

func (r *MemoryRepo[T]) FindBySlug(_ context.Context, slug string) (T, error)

func (r *MemoryRepo[T]) Save(_ context.Context, node T) error

type Module ¶

type Module[T any] struct {
	// contains filtered or unexported fields
}

Module is the core routing and lifecycle unit for a content type T. T must embed Node — its struct must have exported ID, Slug, and Status fields. Use NewModule to construct; Registration onto a ServeMux is done via [Register]. App.Content handles both steps automatically.

func NewModule[T any](proto T, opts ...Option) *Module[T]

secret := []byte("example-secret-key-32-bytes!!!!!")

repo := NewMemoryRepo[*examplePost]()
m := NewModule(&examplePost{},
	At("/posts"),
	Repo(repo),
	Auth(
		Read(Guest),
		Write(Author),
		Delete(Editor),
	),
	Cache(5*time.Minute),
	AIIndex(LLMsTxt, AIDoc),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  secret,
})
app.Content(m)
_ = app.Handler()

func (m *Module[T]) MCPArchive(ctx Context, slug string) error

func (m *Module[T]) MCPCreate(ctx Context, fields map[string]any) (any, error)

func (m *Module[T]) MCPDelete(ctx Context, slug string) error

func (m *Module[T]) MCPGet(ctx Context, slug string) (any, error)

func (m *Module[T]) MCPList(ctx Context, status ...Status) ([]any, error)

func (m *Module[T]) MCPMeta() MCPMeta

func (m *Module[T]) MCPPublish(ctx Context, slug string) error

func (m *Module[T]) MCPSchedule(ctx Context, slug string, at time.Time) error

func (m *Module[T]) MCPSchema() []MCPField

func (m *Module[T]) MCPUpdate(ctx Context, slug string, fields map[string]any) (any, error)

func (m *Module[T]) Register(mux *http.ServeMux)

GET    /{prefix}          → list
GET    /{prefix}/{slug}   → show
POST   /{prefix}          → create
PUT    /{prefix}/{slug}   → update
DELETE /{prefix}/{slug}   → delete

func (m *Module[T]) Stop()

type NavItem ¶

type NavItem struct {
	// ID is the unique identifier. Generated automatically as a UUIDv7 on
	// create when empty.
	ID string

	// Label is the display text rendered in navigations and breadcrumbs.
	Label string

	// Path is the URL prefix for this item, e.g. "/learn". An empty Path
	// marks the item as a ghost — it has no backing route and is
	// non-clickable everywhere.
	Path string

	// ParentID is the ID of the parent NavItem. Empty for top-level items.
	ParentID string

	// Module is the Forge module table name this item maps to, e.g.
	// "posts". Empty for custom or ghost items not backed by a content module.
	Module string

	// Hidden excludes this item from rendered navigation while keeping it
	// accessible in breadcrumbs. A hidden item is still clickable.
	Hidden bool

	// Ghost marks this item as non-clickable everywhere. Ghost items appear
	// in navigation (unless also Hidden) but have no backing route. Use
	// ghost items as structural grouping nodes.
	Ghost bool

	// SortOrder controls the display order within a parent level. Lower
	// values appear first. Items with equal SortOrder are sorted
	// alphabetically by Label.
	SortOrder int

	// Children holds the item's direct children in SortOrder order.
	// Children is populated in memory during tree construction and is
	// never persisted to the database.
	Children []*NavItem
}

NavItem represents a single entry in the navigation tree. Items are stored in the forge_nav table (NavModeDB) or supplied via App.Nav (NavModeCode).

The Hidden and Ghost flags determine where the item appears:

Hidden=false Ghost=false — shown in navigation; in breadcrumb; clickable
Hidden=true  Ghost=false — hidden from navigation; in breadcrumb; clickable
Hidden=false Ghost=true  — shown in navigation; in breadcrumb; not clickable
Hidden=true  Ghost=true  — hidden from navigation; in breadcrumb; not clickable

type NavMode ¶

type NavMode int

NavMode controls how the application's navigation tree is populated. The zero value means no navigation tree is active.

const (
	// NavModeDB populates the navigation tree from the forge_nav database
	// table. Requires [Config.DB] to be non-nil; panics at startup if DB
	// is nil when this mode is selected.
	NavModeDB NavMode = iota + 1

	// NavModeCode populates the navigation tree from items supplied via
	// [App.Nav]. No database access is performed.
	NavModeCode
)

type NavTree ¶

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

NavTree holds the in-memory navigation tree and provides thread-safe access for both reading (templates) and writing (MCP tools).

Obtain a NavTree from App.NavTree after calling App.Handler.

func (n *NavTree) Create(ctx context.Context, item NavItem) (NavItem, error)

func (n *NavTree) Delete(ctx context.Context, id string) error

func (n *NavTree) Get(id string) (NavItem, bool)

func (n *NavTree) HasDB() bool

func (n *NavTree) List() []NavItem

func (n *NavTree) Tree() []NavItem

func (n *NavTree) Update(ctx context.Context, item NavItem) (NavItem, error)

type Node ¶

type Node struct {
	// ID is the UUID v7 primary key. Set by the storage layer on insert;
	// immutable thereafter. See [NewID] and Amendment S1.
	ID string

	// Slug is the URL-safe identifier used in all public URLs. Unique within
	// a module. Auto-generated from the first required string field if not
	// set explicitly. May be changed; the old URL should redirect.
	Slug string

	// Status is the lifecycle state. Forge enforces this on every public
	// endpoint. See Decision 14.
	Status Status

	// PublishedAt is the time the content was first published. Zero until
	// the first transition to Published.
	PublishedAt time.Time `db:"published_at"`

	// ScheduledAt is the time at which a Scheduled item will be published.
	// Nil for all other lifecycle states.
	ScheduledAt *time.Time `db:"scheduled_at"`

	// CreatedAt is set by the storage layer on insert and never updated.
	CreatedAt time.Time `db:"created_at"`

	// UpdatedAt is set by the storage layer on every Save.
	UpdatedAt time.Time `db:"updated_at"`
}

Node is the base type embedded by every Forge content type. It carries the stable UUID identity, the URL slug, and the full content lifecycle.

Content types must embed Node as a value (not a pointer):

type BlogPost struct {
    forge.Node
    Title string `forge:"required"`
    Body  string `forge:"required,min=50"`
}

Never store a Node by pointer inside your content type — the storage and validation layers require a contiguous struct layout.

func (n *Node) GetPublishedAt() time.Time

func (n *Node) GetSlug() string

func (n *Node) GetStatus() Status

type OGDefaults ¶

type OGDefaults struct {
	// Image is the fallback og:image used when a content item's Head.Image.URL
	// is empty. Width and Height are recommended for optimal Twitter Card display.
	Image Image

	// TwitterSite is the twitter:site handle for the site (e.g. "@mycompany").
	// Always emitted on every page; not overridable per item.
	TwitterSite string

	// TwitterCreator is the fallback twitter:creator handle used when the
	// content item's Head.Social.Twitter.Creator is empty.
	TwitterCreator string
}

OGDefaults sets app-level Open Graph and Twitter Card fallback values. Apply via App.SEO; values are merged into every page's Head by forge:head when the content item does not supply its own.

• Image — fallback og:image when [Head.Image].URL is empty.
• TwitterSite — twitter:site handle (e.g. "@mycompany"); always app-level, emitted on every page.
• TwitterCreator — fallback twitter:creator when [Head.Social].Twitter.Creator is empty.

Example:

app.SEO(&forge.OGDefaults{
    Image:          forge.Image{URL: "https://example.com/og.png", Width: 1200, Height: 630},
    TwitterSite:    "@mycompany",
    TwitterCreator: "@editor",
})

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.SEO(&OGDefaults{
	Image:          Image{URL: "https://example.com/og-default.png", Width: 1200, Height: 630},
	TwitterSite:    "@mycompany",
	TwitterCreator: "@editor",
})
_ = app.Handler()

type Option ¶

type Option interface {
	// contains filtered or unexported methods
}

Option configures a Module or App at registration time. Option values are created by functions such as Read, Write, Delete, At, Cache, and forge.On. They are consumed during module or app setup and have no effect after App.Run is called.

var WithoutCSRF Option = withoutCSRFOption{}

func AIIndex(features ...AIFeature) Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.AIIndex(forge.LLMsTxt, forge.LLMsTxtFull, forge.AIDoc),
)

repo := NewMemoryRepo[*examplePost]()
m := NewModule(&examplePost{},
	At("/posts"),
	Repo(repo),
	AIIndex(LLMsTxt, LLMsTxtFull, AIDoc),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.Content(m)
_ = app.Handler()

func At(prefix string) Option

func Auth(opts ...Option) Option

forge.Auth(
    forge.Read(forge.Guest),
    forge.Write(forge.Author),
    forge.Delete(forge.Editor),
)

repo := NewMemoryRepo[*examplePost]()
m := NewModule(&examplePost{},
	At("/posts"),
	Repo(repo),
	Auth(
		Read(Guest),
		Write(Author),
		Delete(Editor),
	),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.Content(m)
_ = app.Handler()

func Cache(ttl time.Duration) Option

func CacheMaxEntries(n int) Option

func ContextFunc(fn func(ctx Context, item any) (any, error)) Option

forge.ContextFunc(func(ctx forge.Context, _ any) (any, error) {
    return docRepo.FindAll(ctx, forge.ListOptions{
        Status: []forge.Status{forge.Published},
    })
})

type DocPage struct {
	Node
	Title string `forge:"required"`
	Body  string
}

docRepo := NewMemoryRepo[*DocPage]()

m := NewModule((*DocPage)(nil),
	At("/docs"),
	Repo(docRepo),
	ContextFunc(func(ctx Context, _ any) (any, error) {
		// Return all published docs for use as a navigation sidebar.
		return docRepo.FindAll(ctx, ListOptions{
			Status: []Status{Published},
		})
	}),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.Content(m)
_ = app.Handler()

func Delete(r Role) Option

func DisableFeed() Option

func Feed(cfg FeedConfig) Option

app.Content(&Post{},
    forge.At("/posts"),
    forge.Feed(forge.FeedConfig{Title: "Blog", Description: "Latest posts"}),
)

func HeadFunc[T any](fn func(Context, T) Head) Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.HeadFunc(func(ctx forge.Context, p *BlogPost) forge.Head {
        return forge.Head{Title: p.Title + " — " + ctx.SiteName()}
    }),
)

func ListHeadFunc[T any](fn func(Context, []T) Head) Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.ListHeadFunc(func(ctx forge.Context, posts []*BlogPost) forge.Head {
        return forge.Head{Title: "All posts — " + ctx.SiteName()}
    }),
)

func MCP(ops ...MCPOperation) Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.MCP(forge.MCPRead, forge.MCPWrite),
)

func ManifestAuth(auth AuthFunc) Option

func Middleware(mws ...func(http.Handler) http.Handler) Option

func On[T any](signal Signal, h func(Context, T) error) Option

forge.On(forge.BeforeCreate, func(ctx forge.Context, p *Post) error {
    p.Author = ctx.User().Name
    return nil
})

repo := NewMemoryRepo[*examplePost]()
m := NewModule(&examplePost{},
	At("/posts"),
	Repo(repo),
	On(AfterPublish, func(_ Context, p *examplePost) error {
		_ = p.Title // access typed fields
		return nil
	}),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.Content(m)
_ = app.Handler()

func Read(r Role) Option

func Redirects(from From, to string) Option

app.Content(&BlogPost{},
    forge.At("/articles"),
    forge.Redirects(forge.From("/posts"), "/articles"),
)

func Repo[T any](r Repository[T]) Option

forge.Repo(forge.NewMemoryRepo[*Post]())

func Social(features ...SocialFeature) Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.Social(forge.OpenGraph, forge.TwitterCard),
)

func (p *BlogPost) Head() forge.Head {
    return forge.Head{
        // ...
        Social: forge.SocialOverrides{
            Twitter: forge.TwitterMeta{
                Card:    forge.SummaryLargeImage,
                Creator: "@alice",
            },
        },
    }
}

repo := NewMemoryRepo[*examplePost]()
m := NewModule(&examplePost{},
	At("/posts"),
	Repo(repo),
	Social(OpenGraph, TwitterCard),
)

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.Content(m)
_ = app.Handler()

func Templates(dir string) Option

{dir}/list.html        — rendered for GET /{prefix}
{dir}/show.html        — rendered for GET /{prefix}/{slug}
{dir}/errors/404.html  — (optional) custom error page for 404 responses

func TemplatesOptional(dir string) Option

func TrustedProxy() Option

func WithoutID() Option

app.Content(&BlogPost{},
    forge.At("/posts"),
    forge.AIIndex(forge.AIDoc),
    forge.WithoutID(),
)

func Write(r Role) Option

type OrganizationDetails ¶

type OrganizationDetails struct {
	Name        string
	URL         string
	Description string
	Logo        Image
}

OrganizationDetails carries the extra fields required for Organization rich results.

type OrganizationProvider ¶

type OrganizationProvider interface{ OrganizationDetails() OrganizationDetails }

OrganizationProvider is implemented by content types that supply organization structured data.

type PageHead ¶

type PageHead struct {
	// Head carries SEO and social metadata for this page.
	Head Head

	// OGDefaults holds the app-level Open Graph and Twitter Card fallback values.
	OGDefaults *OGDefaults

	// AppSchema is a pre-rendered <script type="application/ld+json"> block
	// for app-level structured data.
	AppSchema template.HTML

	// HeadAssets holds the app-level static assets (preconnect, stylesheets,
	// links, scripts) set via [App.SEO] with [HeadAssets].
	HeadAssets *HeadAssets
}

PageHead holds the framework-owned fields that [forge:head] reads. Embed PageHead in any custom handler data struct to enable {{template "forge:head" .}} without using TemplateData.

Example:

type homeData struct {
    forge.PageHead
    Posts []*Post
}

func homeHandler(app *forge.App) http.HandlerFunc {
    tmpl := app.MustParseTemplate("templates/home.html")
    return func(w http.ResponseWriter, r *http.Request) {
        data := homeData{
            PageHead: forge.PageHead{Head: forge.Head{Title: "Home"}},
            Posts:    loadPosts(),
        }
        tmpl.ExecuteTemplate(w, "home.html", data)
    }
}

type homeData struct {
	PageHead
	Featured string
}

data := homeData{
	PageHead: PageHead{
		Head: Head{Title: "Home — My Site"},
	},
	Featured: "Welcome post",
}

// data.Head, data.OGDefaults, data.AppSchema, and data.HeadAssets are all
// accessible at the top level of homeData because PageHead is embedded
// anonymously. forge:head reads them identically to TemplateData[T].
_ = data.Head.Title // "Home — My Site"
_ = data.Featured   // "Welcome post"

type RecipeDetails ¶

type RecipeDetails struct {
	Ingredients []string
	Steps       []HowToStep
}

RecipeDetails carries the extra fields required for Recipe rich results.

type RecipeProvider ¶

type RecipeProvider interface{ RecipeDetails() RecipeDetails }

RecipeProvider is implemented by content types that supply recipe structured data.

type RedirectCode ¶

type RedirectCode int

RedirectCode is the HTTP status code issued for a redirect entry. Use Permanent (301) for URL changes that search engines should follow and update, and Gone (410) for content that has been intentionally removed. 410 signals de-indexing significantly faster than 404.

const (
	// Permanent issues a 301 Moved Permanently response.
	// Use when the resource has moved to a new URL and the change is final.
	Permanent RedirectCode = http.StatusMovedPermanently

	// Gone issues a 410 Gone response.
	// Use when the resource has been intentionally removed.
	// Pass an empty string as the destination to [App.Redirect].
	Gone RedirectCode = http.StatusGone
)

type RedirectEntry ¶

type RedirectEntry struct {
	From     string       // absolute path to match
	To       string       // destination path; empty = 410 Gone
	Code     RedirectCode // Permanent (301) or Gone (410)
	IsPrefix bool         // prefix-rewrite semantics (Decision 17 amendment)
}

RedirectEntry describes a single redirect rule. Obtain entries via App.Redirect or the Redirects module option; do not construct them directly in production code unless building a custom migration tool.

• From is the absolute request path that triggers the rule, e.g. "/posts/hello".
• To is the destination path. An empty To with Code == Gone issues 410.
• IsPrefix, when true, matches any path whose prefix equals From and rewrites the suffix onto To at request time — a single entry covers an entire renamed module prefix with zero per-request allocations beyond the destination string concatenation.

type RedirectStore ¶

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

RedirectStore holds the runtime redirect table. Exact lookups are O(1) map reads; prefix lookups iterate a short slice sorted longest-first, ending on the first match. The store is safe for concurrent use.

func NewRedirectStore() *RedirectStore

func (s *RedirectStore) Add(e RedirectEntry)

func (s *RedirectStore) All() []RedirectEntry

func (s *RedirectStore) Get(path string) (RedirectEntry, bool)

func (s *RedirectStore) Len() int

func (s *RedirectStore) Load(ctx context.Context, db DB) error

func (s *RedirectStore) Remove(ctx context.Context, db DB, from string) error

func (s *RedirectStore) Save(ctx context.Context, db DB, e RedirectEntry) error

type Registrator ¶

type Registrator interface {
	Register(mux *http.ServeMux)
}

Registrator is implemented by any value that can register its HTTP routes on a http.ServeMux. *Module satisfies this interface automatically.

Pass a pre-built *Module to App.Content to register it:

posts := forge.NewModule[*Post](&Post{}, forge.Repo(repo))
app.Content(posts)

type Repository ¶

type Repository[T any] interface {
	FindByID(ctx context.Context, id string) (T, error)
	FindBySlug(ctx context.Context, slug string) (T, error)
	FindAll(ctx context.Context, opts ListOptions) ([]T, error)
	Save(ctx context.Context, node T) error
	Delete(ctx context.Context, id string) error
}

Repository is the storage interface for a content type. Implement it to provide a custom storage backend. Use NewMemoryRepo for in-process testing and prototyping.

type ReviewDetails ¶

type ReviewDetails struct {
	Body        string
	Rating      float64
	BestRating  float64
	WorstRating float64
}

ReviewDetails carries the extra fields required for Review rich results.

type ReviewProvider ¶

type ReviewProvider interface{ ReviewDetails() ReviewDetails }

ReviewProvider is implemented by content types that supply review structured data.

type RobotsConfig ¶

type RobotsConfig struct {
	// Disallow lists URL paths to block for all crawlers (e.g. "/admin").
	Disallow []string

	// Sitemaps appends a Sitemap directive pointing to <baseURL>/sitemap.xml
	// when true. Requires a non-empty baseURL on [App].
	Sitemaps bool

	// AIScraper sets the AI crawler policy. Defaults to [Allow] when zero.
	AIScraper CrawlerPolicy
}

RobotsConfig configures the auto-generated robots.txt. Pass a pointer to App.SEO to register the /robots.txt endpoint:

app.SEO(&forge.RobotsConfig{
    AIScraper: forge.AskFirst,
    Sitemaps:  true,
})

app := New(Config{
	BaseURL: "https://example.com",
	Secret:  []byte("example-secret-key-32-bytes!!!!!"),
})
app.SEO(&RobotsConfig{
	Disallow:  []string{"/admin"},
	Sitemaps:  true,
	AIScraper: AskFirst,
})
_ = app.Handler()

type Role ¶

type Role string

Role is a named permission level. The four built-in roles cover most applications; custom roles can be registered via NewRole.

Roles are stored as plain strings in tokens and sessions. The numeric level is derived at runtime via a registry lookup, not stored with the role name.

const (
	// Guest is the implicit role for unauthenticated requests (level 1).
	Guest Role = "guest"
	// Author can create and manage their own content (level 2).
	Author Role = "author"
	// Editor can manage all content (level 3).
	Editor Role = "editor"
	// Admin has full access including app configuration (level 4).
	Admin Role = "admin"
)

type SEOOption ¶

type SEOOption interface {
	// contains filtered or unexported methods
}

SEOOption is implemented by any value that modifies the app-level SEO configuration. Pass SEOOption values to App.SEO:

app.SEO(&forge.RobotsConfig{AIScraper: forge.AskFirst, Sitemaps: true})

type SQLRepo ¶

type SQLRepo[T any] struct {
	// contains filtered or unexported fields
}

SQLRepo is a production Repository[T] backed by forge.DB. T must embed forge.Node — its fields are mapped to SQL columns via `db` struct tags, falling back to lowercase field names (the same rules as Query and QueryOne).

All queries use $N positional placeholders (PostgreSQL / pgx compatible). Use the Table option to override the automatically derived table name.

func NewSQLRepo[T any](db DB, opts ...SQLRepoOption) *SQLRepo[T]

repo := forge.NewSQLRepo[*Post](db)
m := forge.NewModule((*Post)(nil), forge.Repo(repo))

func (r *SQLRepo[T]) Delete(ctx context.Context, id string) error

func (r *SQLRepo[T]) FindAll(ctx context.Context, opts ListOptions) ([]T, error)

func (r *SQLRepo[T]) FindByID(ctx context.Context, id string) (T, error)

func (r *SQLRepo[T]) FindBySlug(ctx context.Context, slug string) (T, error)

func (r *SQLRepo[T]) Save(ctx context.Context, item T) error

type SQLRepoOption ¶

type SQLRepoOption interface {
	// contains filtered or unexported methods
}

SQLRepoOption configures a SQLRepo. Obtain values via Table.

func Table(name string) SQLRepoOption

repo := forge.NewSQLRepo[*Story](db, forge.Table("stories"))
repo := forge.NewSQLRepo[*BlogPost](db, forge.Table("posts"))

type Scheduler ¶

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

Scheduler drives the Scheduled→Published transition for all content modules registered with App.Content. A single background goroutine runs with an adaptive timer: after each tick the timer is reset to fire at the soonest remaining ScheduledAt across all modules, falling back to 60 seconds when no scheduled items exist.

The Scheduler is created and started by App.Run and stopped as part of graceful shutdown. Applications do not create Schedulers directly.

func (s *Scheduler) Start(ctx context.Context)

func (s *Scheduler) Wait()

type ScriptTag ¶

type ScriptTag struct {
	Src   string      // external script URL; empty means inline
	Body  template.JS // inline JavaScript body; used when Src is empty
	Async bool        // adds async attribute (external scripts only)
	Defer bool        // adds defer attribute (external scripts only)
}

ScriptTag declares a single <script> element. Src loads an external script; Body inlines a JavaScript body when Src is empty. Body is typed as html/template.JS — convert a string literal with template.JS("…") to mark it as safe for emission inside a <script> block; never use this with user-supplied content. Async and Defer are only emitted for external scripts (Src non-empty).

type Signal ¶

type Signal string

Signal identifies a lifecycle event fired by a content module. Handlers are registered with On and receive the content value as their concrete type T — no type assertion required.

const (
	// BeforeCreate fires before a new content item is persisted.
	// Return an error to abort the operation.
	BeforeCreate Signal = "before_create"

	// AfterCreate fires after a new content item has been persisted.
	// Runs asynchronously — errors and panics are logged, never returned.
	AfterCreate Signal = "after_create"

	// BeforeUpdate fires before an existing content item is updated.
	// Return an error to abort the operation.
	BeforeUpdate Signal = "before_update"

	// AfterUpdate fires after a content item has been updated.
	// Runs asynchronously — errors and panics are logged, never returned.
	AfterUpdate Signal = "after_update"

	// BeforeDelete fires before a content item is deleted.
	// Return an error to abort the operation.
	BeforeDelete Signal = "before_delete"

	// AfterDelete fires after a content item has been deleted.
	// Runs asynchronously — errors and panics are logged, never returned.
	AfterDelete Signal = "after_delete"

	// AfterPublish fires after a content item transitions to Published.
	// Runs asynchronously — triggers sitemap and feed regeneration.
	AfterPublish Signal = "after_publish"

	// AfterUnpublish fires after a content item is moved out of Published status.
	// Runs asynchronously — triggers sitemap and feed regeneration.
	AfterUnpublish Signal = "after_unpublish"

	// AfterArchive fires after a content item transitions to Archived.
	// Runs asynchronously — triggers sitemap and feed regeneration.
	AfterArchive Signal = "after_archive"

	// SitemapRegenerate is fired internally after AfterPublish, AfterUnpublish,
	// AfterArchive, and AfterDelete. It is debounced to coalesce burst changes
	// into a single sitemap and feed rebuild.
	SitemapRegenerate Signal = "sitemap_regenerate"
)

type SitemapConfig ¶

type SitemapConfig struct {
	// ChangeFreq is the expected update frequency for URLs in this module.
	// Defaults to [Weekly] when empty.
	ChangeFreq ChangeFreq

	// Priority is the relative importance of URLs in this module, in the range
	// 0.0–1.0. Defaults to 0.5 when zero or negative.
	Priority float64
}

SitemapConfig configures the per-module sitemap fragment. Pass it to App.Content as an option alongside At, Cache, and similar options.

app.Content(posts, forge.SitemapConfig{ChangeFreq: forge.Weekly, Priority: 0.8})

ChangeFreq defaults to Weekly when zero. Priority defaults to 0.5 when zero or negative.

type SitemapEntry ¶

type SitemapEntry struct {
	// Loc is the canonical URL of the page.
	Loc string

	// LastMod is the date-time the content was last modified. It is formatted
	// as a date-only string (YYYY-MM-DD) in the output. Zero value is omitted.
	LastMod time.Time

	// ChangeFreq is the expected update frequency. Defaults to [Weekly].
	ChangeFreq ChangeFreq

	// Priority is the relative importance, 0.0–1.0. Defaults to 0.5.
	Priority float64
}

SitemapEntry is a single URL entry in a sitemap fragment. A zero LastMod is omitted from the XML output.

func SitemapEntries[T SitemapNode](items []T, baseURL string, cfg SitemapConfig) []SitemapEntry

type SitemapNode ¶

type SitemapNode interface {
	Headable
	GetSlug() string
	GetPublishedAt() time.Time
	GetStatus() Status
}

SitemapNode is the type constraint for SitemapEntries. It is satisfied by any pointer to a struct that embeds Node and implements Headable. All Forge content types that embed Node satisfy this constraint automatically after Amendment A2.

type SitemapPrioritiser ¶

type SitemapPrioritiser interface {
	SitemapPriority() float64
}

SitemapPrioritiser may be implemented by content types to provide a per-item priority override in the sitemap. When not implemented, [SitemapConfig.Priority] is used (defaulting to 0.5).

type SitemapStore ¶

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

SitemapStore holds the latest generated sitemap fragments in memory. Forge populates it automatically via the debouncer on every publish/unpublish event. It is safe for concurrent use by multiple goroutines.

func NewSitemapStore() *SitemapStore

func (s *SitemapStore) Get(path string) ([]byte, bool)

func (s *SitemapStore) Handler() http.Handler

func (s *SitemapStore) IndexHandler(baseURL string) http.Handler

func (s *SitemapStore) Paths() []string

func (s *SitemapStore) Set(path string, data []byte)

type SocialFeature ¶

type SocialFeature int

SocialFeature selects which social sharing meta tags forge:head emits for a module. Use the predefined constants OpenGraph and TwitterCard.

const (
	// OpenGraph enables Open Graph meta tags (og:title, og:description,
	// og:image, og:type, og:url, and article:* for Article content).
	OpenGraph SocialFeature = 1

	// TwitterCard enables Twitter Card meta tags (twitter:card, twitter:title,
	// twitter:description, twitter:image, twitter:creator).
	TwitterCard SocialFeature = 2
)

type SocialOverrides ¶

type SocialOverrides struct {
	Twitter TwitterMeta // Twitter Card overrides for this item
}

SocialOverrides carries per-item social sharing overrides. Set on [Head.Social] to customise Open Graph and Twitter Card output.

type Status ¶

type Status string

Status is the content lifecycle state. All content types embed Node and therefore always carry a Status. Forge enforces lifecycle rules on all public endpoints — non-Published content is never publicly visible.

const (
	// Draft is the default state for newly created content. Not publicly visible.
	Draft Status = "draft"

	// Published content is publicly visible and included in sitemaps, feeds,
	// and AI indexes.
	Published Status = "published"

	// Scheduled content will be automatically transitioned to Published at
	// [Node.ScheduledAt]. Not publicly visible until the transition fires.
	Scheduled Status = "scheduled"

	// Archived content has been retired. Not publicly visible. Does not appear
	// in sitemaps or feeds. Returns 410 Gone from public endpoints.
	Archived Status = "archived"
)

type TemplateData ¶

type TemplateData[T any] struct {
	// PageHead promotes Head, OGDefaults, AppSchema, and HeadAssets to the
	// top level of TemplateData. Templates access them as .Head, .OGDefaults,
	// .AppSchema, and .HeadAssets — identical to before embedding was used.
	PageHead

	// Content is the page payload — a single item for show templates,
	// a slice for list templates.
	Content T

	// User is the authenticated user for this request. Zero value ([GuestUser])
	// when the request is unauthenticated.
	User User

	// Request is the live *http.Request for this response. Use it in
	// templates for URL introspection, query parameters, or helpers that
	// require the request (e.g. [forge_csrf_token]).
	Request *http.Request

	// SiteName is the hostname extracted from [Config.BaseURL] at module
	// registration time (e.g. "example.com"). Uses the hostname rather than
	// [Context.SiteName] because SiteName() always returns "" in v1.
	SiteName string

	// Extra holds the value returned by the [ContextFunc] option for this
	// request. It is nil when no ContextFunc is configured. Templates access
	// it as {{.Extra}} and may assign it to a typed variable using a template
	// helper or direct assignment:
	//
	//	{{- $nav := .Extra}}
	//	{{template "sidebar" $nav}}
	Extra any

	// Nav holds the top-level navigation items with their Children populated.
	// It is nil when no navigation tree is configured. Templates access it
	// as {{.Nav}} to render site-wide navigation:
	//
	//	{{range .Nav}}
	//	  <a href="{{.Path}}">{{.Label}}</a>
	//	{{end}}
	Nav []NavItem
}

TemplateData is the value passed to every HTML template rendered by Forge. T is the content type for show handlers (e.g. *BlogPost) or a slice type for list handlers (e.g. []*BlogPost).

The framework-owned head fields (Head, OGDefaults, AppSchema, HeadAssets) are promoted from the embedded PageHead field and remain accessible at the top level of the struct — existing template calls like {{.Head.Title}} are unchanged.

To use {{template "forge:head" .}} in a custom handler without TemplateData, embed PageHead directly in your own data struct:

type homeData struct {
    forge.PageHead
    Posts []*Post
}

Show handler:

TemplateData[*BlogPost]{
    PageHead: forge.PageHead{Head: post.Head()},
    Content:  post,
    User:     ctx.User(),
    Request:  r,
    SiteName: "example.com",
}

In templates:

{{template "forge:head" .}}
<h1>{{.Content.Title}}</h1>
<p>Welcome, {{.User.Name}}</p>

func NewTemplateData[T any](ctx Context, content T, head Head, siteName string) TemplateData[T]

type TokenRecord ¶

type TokenRecord struct {
	// ID is the SHA-256 hex fingerprint of the raw token. Tokens are never
	// stored in plaintext; only this fingerprint is persisted.
	ID string

	// Name is the human-readable label provided when the token was created.
	Name string

	// Role is the role string assigned to this token (e.g. "author", "editor").
	Role string

	// ExpiresAt is the UTC time after which the token is no longer valid.
	ExpiresAt time.Time

	// RevokedAt is the UTC time at which this token was revoked. A zero value
	// means the token has not been revoked.
	RevokedAt time.Time

	// CreatedAt is the UTC time at which the token was created.
	CreatedAt time.Time
}

TokenRecord is a named bearer token entry stored in the forge_tokens table. Retrieve records with TokenStore.List; revoke with TokenStore.Revoke.

type TokenStore ¶

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

TokenStore manages named, revocable bearer tokens stored in a forge_tokens database table. Use NewTokenStore to create one; wire it into [Config.TokenStore] to activate database-backed token verification.

The forge_tokens table must exist before the application starts. Forge does not create or migrate it automatically. Required DDL:

CREATE TABLE forge_tokens (
    id         TEXT PRIMARY KEY,  -- SHA-256 hex fingerprint of the raw token
    name       TEXT NOT NULL,
    role       TEXT NOT NULL,
    expires_at TEXT NOT NULL,     -- RFC3339 UTC
    revoked_at TEXT,              -- NULL when not revoked; RFC3339 UTC when revoked
    created_at TEXT NOT NULL      -- RFC3339 UTC
);

func NewTokenStore(db DB, secret string) *TokenStore

func (ts *TokenStore) Create(ctx context.Context, name, role string, ttl time.Duration) (string, error)

func (ts *TokenStore) List(ctx context.Context) ([]TokenRecord, error)

func (ts *TokenStore) Revoke(ctx context.Context, id string) error

type TwitterCardType ¶

type TwitterCardType string

TwitterCardType is the value of the twitter:card meta property. Use the predefined constants Summary, SummaryLargeImage, AppCard, PlayerCard.

const (
	Summary           TwitterCardType = "summary"             // small card with title and description
	SummaryLargeImage TwitterCardType = "summary_large_image" // large image above the title
	AppCard           TwitterCardType = "app"                 // deep-link to a mobile app
	PlayerCard        TwitterCardType = "player"              // inline video or audio player
)

type TwitterMeta ¶

type TwitterMeta struct {
	Card    TwitterCardType // overrides the default card type; empty uses a sensible default
	Creator string          // @handle of the content author; populates twitter:creator
}

TwitterMeta carries per-item Twitter Card overrides. Set on [Head.Social] to customise Twitter Card output for a specific content item.

type User ¶

type User struct {
	// ID is the user's stable UUID. Empty for unauthenticated guests.
	ID string

	// Name is the display name. Empty for unauthenticated guests.
	Name string

	// Roles is the set of roles held by this user. Forge's hierarchical
	// permission checks ([HasRole], [IsRole]) operate on this slice.
	Roles []Role
}

User represents an authenticated identity. The zero value is an unauthenticated guest — equivalent to GuestUser. See Amendment R3.

The User type is declared here (context.go) rather than auth.go because [Context.User] returns it and context.go is in a lower dependency layer than auth.go. auth.go adds authentication machinery on top of this type.

func VerifyBearerToken(r *http.Request, secret []byte, store *TokenStore) (User, bool)

func (u User) HasRole(role Role) bool

func (u User) Is(role Role) bool

type Validatable ¶

type Validatable interface {
	Validate() error
}

Validatable is implemented by content types that have business-rule validation beyond struct-tag constraints. RunValidation calls Validate() after tag validation passes — if tags fail, Validate() is not called.

func (p *BlogPost) Validate() error {
    if p.Status == forge.Published && len(p.Tags) == 0 {
        return forge.Err("tags", "required when publishing")
    }
    return nil
}

type ValidationError ¶

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

ValidationError is returned when one or more fields fail validation. It implements forge.Error with HTTP status 422.

Create with Err for a single field, or Require to collect several.

func Err(field, message string) *ValidationError

return forge.Err("title", "required")

func (e *ValidationError) Code() string

func (e *ValidationError) Error() string

func (e *ValidationError) HTTPStatus() int

func (e *ValidationError) Public() string