gnoweb

type AliasKind int

type AliasTarget struct {
	Value string
	Kind  AliasKind
	// Title and Description come from a static page's front matter, and are
	// empty for every other alias.
	Title       string
	Description string
}

type AppConfig struct {
	// UnsafeHTML, if enabled, allows to use HTML in the markdown.
	UnsafeHTML bool
	// Analytics enables SimpleAnalytics.
	Analytics bool
	// AnalyticsHostname, when non-empty, is rendered as data-hostname on the
	// SimpleAnalytics script tag to override the hostname SA reports.
	// Set this when the site listens on a host SA would otherwise report
	// incorrectly (for example a non-default port in local development).
	AnalyticsHostname string
	// NodeRemote is the remote address of the gno.land node.
	NodeRemote string
	// NodeRequestTimeout define how much time a request to the remote node should live before timeout.
	NodeRequestTimeout time.Duration
	// RemoteHelp is the remote of the gno.land node, as used in the help page.
	RemoteHelp string
	// AssetsPath is the base path to the gnoweb assets.
	AssetsPath string
	// NoAssetsCache disables assets caching.
	NoAssetsCache bool
	// ChainID is the chain id, used for constructing the help page.
	ChainID string
	// FaucetURL, if specified, will be the URL to which `/faucet` redirects.
	FaucetURL string
	// Domain is the domain used by the node.
	Domain string

	// CanonicalOrigin is the public origin this deployment is reachable at,
	// scheme included. Empty means no canonical tag: a canonical naming a host
	// the visitor did not reach tells a crawler the content belongs elsewhere,
	// and every deployment but one would be claiming gno.land's.
	CanonicalOrigin string
	// NoIndex keeps this deployment out of search engines (testnets, staging):
	// every page is noindex, nofollow with no canonical, and no sitemap is
	// served. Off by default, so a forgotten flag never drops a site from search.
	NoIndex bool
	// Banner, if set, displays a site-wide banner above the header.
	Banner components.BannerData
	// RealmNotice, if set, is shown as the header's second row on pages of
	// packages outside TrustedPaths.
	RealmNotice components.RealmNotice
	// TrustedPaths are namespaces or package paths ("gnoland", "gnoswap/v1/pool";
	// no "/r/" or "/p/" prefix), or "*" for every path, whose pages are official: they never show
	// RealmNotice, may lend their own heading and summary to the page
	// metadata, keep their internal links followed, and are indexed whatever
	// IndexCommunity says.
	TrustedPaths []string
	// IndexCommunity says which pages outside TrustedPaths search engines may
	// index; the others get noindex, nofollow and no canonical.
	IndexCommunity CommunityIndex
	// Aliases is a map of aliases pointing to another path or a static file.
	Aliases map[string]AliasTarget
	// RenderConfig defines the default configuration for rendering realms and source files.
	RenderConfig RenderConfig
	// StateRateLimitPerMinute caps the per-IP request rate against
	// ?state* URLs and, in a separate bucket, $search (also used as the
	// token-bucket burst). 0 ⇒ the HTTPHandler default (1200/min).
	// ADR-003 §Resource bounds.
	StateRateLimitPerMinute int
	// StateRateLimitTrustedProxies is the list of trusted reverse-proxy
	// CIDRs (or bare IPs) for the per-IP rate limiter. X-Real-IP is honored
	// only for connections originating inside one of these networks, and so
	// is X-Forwarded-Host for the page origin (shareable links, AI prompts);
	// empty (the default) trusts nothing, so untrusted deployments never
	// trust attacker-controlled headers. ADR-003 §Resource bounds.
	StateRateLimitTrustedProxies []string
	// IndexerURL, when non-empty, is the GraphQL endpoint of a tx-indexer
	// gnoweb consults for search qualifiers the RPC node cannot answer
	// (transactions, account activity, source-wide text search).
	//
	// Empty is the default and the whole feature switch: with no indexer,
	// gnoweb makes no outbound request beyond its RPC node, and the
	// qualifiers that would need one are not registered — they do not
	// autocomplete and cannot be typed into a failing search. Indexer data is
	// never consensus data and is labelled as such wherever it appears.
	IndexerURL string
	// IndexerToken, when set, is sent as a bearer credential to the indexer.
	IndexerToken string
	// MaxConcurrentRPC caps in-flight outbound RPCs per gnoweb instance
	// against the chain node. 0 ⇒ the rpcClient default (32). Tighten on
	// chain nodes under pressure; relax when capacity allows. ADR-003
	// §Resource bounds.
	MaxConcurrentRPC int
}

type ClientAdapter interface {
	// Realm fetch the content of a realm from a given path and
	// return the data.
	Realm(ctx context.Context, path, args string) ([]byte, error) // raw Render() bytes

	// File fetches the source file from a given package path and
	// filename. `height = 0` queries the latest block; positive values
	// pin the query to that historical height.
	File(ctx context.Context, path, filename string, height int64) ([]byte, FileMeta, error)

	// ListFiles lists all source files available in a specified
	// package path. `height = 0` queries the latest block; non-zero
	// pins the listing to a historical block.
	ListFiles(ctx context.Context, path string, height int64) ([]string, error)

	// QueryPath list any path given the specified prefix
	ListPaths(ctx context.Context, prefix string, limit int) ([]string, error)

	// Doc retrieves the JSON doc suitable for printing from a
	// specified package path. `height = 0` queries the latest block;
	// any positive value pins the query to that historical height.
	Doc(ctx context.Context, path string, height int64) (*doc.JSONDocumentation, error)

	// StatePkg retrieves the root state tree for a package. `height
	// = 0` queries the latest block; positive values are forwarded
	// to ABCI as-is.
	StatePkg(ctx context.Context, path string, height int64) ([]byte, error)

	// StateObject retrieves the children of an object by ObjectID at
	// the given block height (0 for latest).
	StateObject(ctx context.Context, oid string, height int64) ([]byte, error)

	// StateType retrieves a type definition by TypeID at the given
	// block height (0 for latest).
	StateType(ctx context.Context, typeId string, height int64) ([]byte, error)

	// PackageMeta reports whether a path holds a live package, one parked
	// awaiting an approver, or nothing. An absent path is a nil error with
	// status "absent", not ErrClientPackageNotFound: the caller needs to tell
	// "nothing here" from "the node did not answer".
	PackageMeta(ctx context.Context, path string) (*vm.PackageMeta, error)

	// Eval evaluates a read-only Gno expression (`vm/qeval`) and returns the
	// raw result, one line per return value. pkgPath carries no domain, since
	// the client adds its own, and no dot: the node splits pkgPath from expr on
	// the first dot after the first slash. expr is the caller's to keep safe.
	Eval(ctx context.Context, pkgPath, expr string) ([]byte, error)
}

type CommunityIndex int

type FileMeta struct {
	Lines  int
	SizeKB float64
}

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

type HTTPHandler struct {
	Logger   *slog.Logger
	Static   StaticMetadata
	Client   ClientAdapter
	Renderer Renderer
	Aliases  map[string]AliasTarget
	Timeout  time.Duration

	// State is the feature/state handler that owns every ?state* URL.
	// Built in NewHTTPHandler so the wire-in dispatch hook is a single
	// method call (ADR-003 §Architecture).
	State *state.Handler
	// Search is the feature/omnisearch handler that owns every $search URL.
	Search *omnisearch.Handler
	// ChainMap is the feature/chainmap handler: the map of a listing, and the
	// dependencies page with its importers.
	ChainMap *chainmap.Handler
	// contains filtered or unexported fields
}

type HTTPHandlerConfig struct {
	Meta          StaticMetadata
	ClientAdapter ClientAdapter
	Renderer      Renderer
	Aliases       map[string]AliasTarget
	// TrustedPaths — see AppConfig field of the same name.
	TrustedPaths []string
	// IndexCommunity — see AppConfig field of the same name.
	IndexCommunity CommunityIndex
	Timeout        time.Duration
	// NoIndex — see AppConfig field of the same name.
	NoIndex bool
	// StateRateLimitPerMinute caps per-IP requests against ?state* URLs.
	// 0 ⇒ defaultRateLimitPerMinute. Also used as the token-bucket
	// burst. ADR-003 §Resource bounds.
	StateRateLimitPerMinute int
	// StateRateLimitTrustedProxies — see AppConfig field of the same name.
	// Also gates X-Forwarded-Host in requestOrigin.
	StateRateLimitTrustedProxies []string
	// Directory lists realm and package paths for the search feature.
	// Optional: callers that already have one — the router does, for
	// /search.json — pass it so both share a singleflight group. Nil builds
	// one here.
	Directory RealmDirectory
	// Indexer, when non-nil, enables the indexer-backed search qualifiers.
	// Leave it nil, never a typed nil pointer: the interface is what
	// feature/omnisearch tests to decide whether those qualifiers exist.
	Indexer omnisearch.Indexer
}

type MockClient struct {
	Packages map[string]*MockPackage // path -> package
}

type MockPackage struct {
	Path      string
	Domain    string
	Files     map[string]string // filename -> body
	Functions []*doc.JSONFunc
	// Imports are what vm/qdoc reports the package imports.
	Imports []string
	// Inert stages a package that was submitted but not yet approved. The
	// other methods still refuse it the way the chain does -- Render and the
	// file queries read the live key space -- so a test gets the real shape.
	Inert bool
	// Pending stages a redeploy parked over a live package.
	Pending bool
	// Reason overrides the parked reason; defaults to awaiting-an-approver.
	Reason string
}

type PathsResult struct {
	Realms   []string
	Packages []string

	// Truncated reports that a listing came back at the cap, so the chain
	// holds paths this result does not name. It is part of the answer: a
	// silent cap is how a search comes to say "no such realm" about a realm
	// that exists, and the lexicographic order of the underlying iterator
	// means the paths dropped are always the same ones.
	Truncated bool
}

type RealmDirectory interface {
	// Paths returns the realm (/r/) and package (/p/) paths known to the chain.
	Paths(ctx context.Context) (PathsResult, error)
}

type RealmRenderContext struct {
	ChainId string
	Remote  string
	Domain  string
	// Links says which links of the document search engines may follow.
	Links md.LinkPolicy
}

type RenderConfig struct {
	ChromaStyle     *chroma.Style
	ChromaDarkStyle *chroma.Style
	ChromaOptions   []chromahtml.Option
	GoldmarkOptions []goldmark.Option
	// IPFSGateway is the gateway origin, such as DefaultIPFSGateway, that
	// ipfs:// URLs and URLs on the gateways in markdown's
	// ipfsRewrittenGateways are rewritten to in realm markdown. Empty
	// disables the rewrite. NewRouter rejects an invalid value;
	// NewHTMLRenderer, which knows neither the chain domain nor the
	// canonical origin, ignores a malformed one.
	IPFSGateway string
}

type Renderer interface {
	RenderRealm(w io.Writer, u *weburl.GnoURL, src []byte, ctx RealmRenderContext) (md.RealmMeta, error)
	RenderSource(w io.Writer, name string, src []byte) error
	// RenderDocumentation renders doc-context markdown (from vm/qdoc) to HTML.
	// Fenced and indented code blocks are wrapped in collapsible <details>
	// with Chroma highlighting. HTML escaping is delegated to Goldmark.
	RenderDocumentation(w io.Writer, src []byte) error
}

type StaticMetadata struct {
	Domain            string
	CanonicalOrigin   string
	AssetsPath        string
	ChromaPath        string
	RemoteHelp        string
	ChainId           string
	Analytics         bool
	AnalyticsHostname string
	AssetsVersion     string
	Banner            components.BannerData
	RealmNotice       components.RealmNotice
}