dtd

type AttrDefault int

type Attribute struct {
	Element string
	Name    string
	// Type is the declared type: CDATA, ID, IDREF, IDREFS, NMTOKEN,
	// NMTOKENS, ENTITY, ENTITIES, NOTATION, or ENUMERATION for a
	// parenthesised list.
	//
	// XML 1.0 §3.3.1 closes the set to those; anything else is kept verbatim
	// so Validate can report it rather than dropping it. A type it does not
	// recognise is a type it cannot enforce, and saying so is the only way a
	// caller can tell a checked attribute from an unchecked one.
	Type string
	// Enum holds the permitted values of an enumeration or NOTATION type.
	Enum    []string
	Default AttrDefault
	Value   string
}

type ContentKind int

type DTD struct {
	// Elements maps an element name to its content model.
	Elements map[string]*Element
	// Attributes maps an element name to its declared attributes.
	Attributes map[string][]*Attribute
	// Notations is the set of names declared by <!NOTATION>.
	//
	// It exists only so that Validate can apply XML 1.0 §3.3.1's rule that
	// every name in a NOTATION attribute's enumeration be declared. The
	// declaration's own system or public identifier is data for the
	// application, not for validation, so nothing here keeps it.
	Notations map[string]bool
	// Unparsed is the set of entity names declared with an NDATA notation.
	//
	// §3.3.1 makes these, and only these, the permitted values of an ENTITY
	// or ENTITIES attribute: an entity with replacement text is parsed and
	// naming it there is a validity error just as naming an undeclared one
	// is.
	Unparsed map[string]bool
	// HasExternalSubset records that the DOCTYPE named a SYSTEM or PUBLIC
	// identifier.
	//
	// Parse fetches nothing, so with it this means validation is against the
	// internal subset alone and callers are told rather than misled. Load
	// with a Resolver does fetch, and then this says only that there was one
	// — ExternalSubset holds what was read.
	HasExternalSubset bool
	// ExternalSubset is the external subset's text as it stood after
	// parameter-entity substitution and conditional-section resolution, when
	// Load read one. Empty otherwise.
	//
	// It is the text rather than the declarations because the declarations
	// are already merged into Elements and Attributes; this exists so a
	// caller can see what the DOCTYPE actually pulled in, which for a modular
	// DTD is not something any single file contains.
	ExternalSubset string
}

type Element struct {
	Name string
	Kind ContentKind
	// Mixed is the set of names a mixed model admits. Order and repetition
	// are unconstrained there, so a set is the whole model.
	Mixed map[string]bool
	// Particle is the compiled model for ContentChildren, expressed in xsd's
	// component model so that the existing automaton can run it.
	Particle *xsd.Particle
}

type Error struct {
	// Path locates the element, as "/root/child".
	Path string
	// Message says what was wrong.
	Message string
}

type Errors struct{ Errors []*Error }

type FileResolver struct {
	// Root confines every read. A system identifier that resolves outside
	// it, whether by "..", by an absolute path, or through a symlink, is
	// refused before the file is opened.
	//
	// An empty Root means the process's working directory, which is almost
	// never what a caller wants for an untrusted document — set it.
	Root string

	// MaxBytes bounds one file this resolver reads. Zero means
	// DefaultMaxResolverBytes; a negative value means no limit, for a DTD
	// the caller produced itself.
	//
	// It is a second bound rather than a duplicate of
	// LoadOptions.MaxExternalBytes: that one bounds the whole load and is
	// applied after the read, while this bounds what one call puts in memory
	// at all. The loader's LimitReader already caps the read, so this exists
	// for callers who use the resolver directly.
	MaxBytes int64
}

type LoadOptions struct {
	// Resolver is how an external subset's system identifier becomes bytes.
	//
	// Nil — the zero value — means nothing is fetched, and a DOCTYPE naming
	// an external subset is refused with ErrNoResolver rather than validated
	// against half a DTD. It is off by default because a resolver hands
	// control of what this process reads to whoever wrote the DOCTYPE, which
	// for an untrusted document is the attacker. Pass a FileResolver rooted
	// at the directory the DTD really lives in to say what may be read.
	Resolver Resolver

	// BaseURI is the URI the DOCTYPE's own system identifier resolves
	// against, normally the document's. Empty is permitted; a resolver that
	// needs one will say so.
	BaseURI string

	// InternalSubsetOnly validates against the internal subset alone,
	// without fetching anything, and without the ErrNoResolver refusal.
	//
	// It exists so that the old behaviour is still reachable, but only by
	// asking for it. The resulting DTD has HasExternalSubset set, so a
	// caller can still see that it is partial, and AllowUndeclared is the
	// companion that makes a partial subset usable.
	InternalSubsetOnly bool

	// MaxExternalDocuments bounds how many external resources one load may
	// read — the subset itself and every parameter-entity module it pulls
	// in. Zero means DefaultMaxExternalDocuments; a negative value means no
	// limit, for a DTD the caller produced itself.
	MaxExternalDocuments int

	// MaxExternalBytes bounds the total bytes read from external resources.
	// Zero means DefaultMaxExternalBytes; a negative value means no limit.
	MaxExternalBytes int64

	// MaxEntityBytes bounds the total expanded size of parameter entities,
	// across both subsets. Zero means DefaultMaxEntityBytes; a negative
	// value means no limit.
	//
	// This is the billion-laughs bound. It is charged on the same counter as
	// the bytes read, so a bomb whose halves live in different subsets meets
	// one budget rather than one per subset.
	MaxEntityBytes int64
}

type MapResolver struct {
	// Docs maps a system identifier to its text.
	Docs map[string]string
}

type Options struct {
	// MaxErrors stops after this many failures. Zero means
	// DefaultMaxErrors; a negative value means no limit.
	//
	// A document wrong in every element would otherwise produce an error per
	// element, which helps nobody and costs memory proportional to the input.
	MaxErrors int

	// AllowUndeclared skips elements the DTD says nothing about instead of
	// reporting them.
	//
	// Strictly, an undeclared element is a validity error: a DTD is a closed
	// description, unlike a schema where a wildcard may admit the unknown.
	// But a document whose DOCTYPE names an *external* subset and declares
	// only a few things internally is the common real-world shape — the
	// W3C's own RFC 3986 type library declares one element and one attribute
	// list, purely so that an external DTD's attributes work — and validating
	// that against its internal subset alone reports every other element as
	// undeclared, which is noise rather than a finding.
	//
	// Off by default, so the strict reading is what a caller gets unless they
	// ask otherwise. Turn it on when the DTD is known to be partial;
	// HasExternalSubset is how to detect that case.
	AllowUndeclared bool
}

type Resolver interface {
	ResolveExternal(systemID, publicID, base string) (io.ReadCloser, string, error)
}