gnoweb

type AliasKind int

type AliasTarget struct {
	Value string
	Kind  AliasKind
}

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
	// 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) whose pages never show RealmNotice.
	TrustedPaths []string
	// 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 (also used as the token-bucket burst). 0 ⇒ the
	// HTTPHandler default (100/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
	// 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 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
	// 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
	Timeout      time.Duration
	// StateRateLimitPerMinute caps per-IP requests against ?state* URLs.
	// 0 ⇒ defaultStateRateLimitPerMinute. 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
}

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
	// 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 RealmDirectory interface {
	// Paths returns the realm (/r/) and package (/p/) paths known to the chain.
	Paths(ctx context.Context) (realms, packages []string, err error)
}

type RealmRenderContext struct {
	ChainId string
	Remote  string
	Domain  string
}

type RenderConfig struct {
	ChromaStyle     *chroma.Style
	ChromaDarkStyle *chroma.Style
	ChromaOptions   []chromahtml.Option
	GoldmarkOptions []goldmark.Option
}

type Renderer interface {
	RenderRealm(w io.Writer, u *weburl.GnoURL, src []byte, ctx RealmRenderContext) (md.Toc, 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
	AssetsPath        string
	ChromaPath        string
	RemoteHelp        string
	ChainId           string
	Analytics         bool
	AnalyticsHostname string
	AssetsVersion     string
	Banner            components.BannerData
	RealmNotice       components.RealmNotice
}