@nmnmcc/ability 2.0.7 → 2.1.2

package/src/internal/json.ts

@@ -1,8 +1,8 @@
 /**
- * The JSON form of a condition. The decoder is a plain walk with two limits:
- * it goes at most `conditionDepth` levels down, and it reads at most
- * `jsonNodes` objects and array items, with a shared object counted for each
- * place. So no input can fill the stack or take a very long time. It makes
+ * The JSON form of a condition. The decoder is a walk of the trampoline, so a
+ * deep input does not fill the stack. It reads at most `jsonNodes` objects
+ * and array items, with a shared object counted for each place, so no input
+ * can take a very long time. It makes
  * each node with its constructor, and it reads only the own data fields of
  * the input, as a condition reads a value.
  */
@@ -12,7 +12,9 @@ import * as Result from "effect/Result"
 import type * as SchemaIssue from "effect/SchemaIssue"
 import * as Limits from "./limits.ts"
 import * as Nodes from "./nodes.ts"
+import * as Place from "./place.ts"
 import { readPart } from "./read.ts"
+import * as Trampoline from "./trampoline.ts"
 
 type Node = Nodes.Node
 
@@ -27,84 +29,123 @@ export class Problem extends Data.TaggedError("Problem")<{
 	readonly issue?: SchemaIssue.Issue | undefined
 }> {}
 
-/** The count of the objects and items that one decode has read. It belongs to one decode. */
+/**
+ * The count of the objects and items that one decode has read, with the
+ * limits of the decode. It belongs to one decode.
+ */
 export interface Budget {
 	used: number
+	readonly limits: Limits.Limits
 }
 
 export const problem = (path: ReadonlyArray<PropertyKey>, message: string) =>
 	new Problem({ path, message })
 
+/**
+ * The problem at a place of the input. A decoder keeps the place of each
+ * part, which shares the path of its parent, and makes the full path only for
+ * a problem: see `Place`.
+ */
+export const problemAt = (at: Place.Place | undefined, message: string) =>
+	problem(Place.pathOf(at), message)
+
 /** Counts `count` more objects or items, and stops past the limit. */
 export const spend = (
 	budget: Budget,
 	count: number,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 ): void => {
 	budget.used += count
-	if (budget.used > Limits.jsonNodes) {
-		throw problem(
-			path,
-			`The input has more than ${String(Limits.jsonNodes)} objects and items. The most is ${String(Limits.jsonNodes)}.`,
+	const most = budget.limits.jsonNodes
+	if (budget.used > most) {
+		throw problemAt(
+			at,
+			`The input has more than ${String(most)} objects and items. The most is ${String(most)}.`,
 		)
 	}
 }
 
-/** Reads a field of the input. A field that is not plain data is a problem. */
+/**
+ * Reads a field of the input at the place `at`. A field that is not plain
+ * data is a problem.
+ */
 export const read = (
 	input: unknown,
 	name: string,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 ): unknown => {
 	try {
 		return readPart(input, name)
 	} catch {
-		throw problem([...path, name], `The field "${name}" is not plain data`)
+		throw problemAt(Place.at(at, name), `The field "${name}" is not plain data`)
 	}
 }
 
 export const readString = (
 	input: unknown,
 	name: string,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 ): string => {
-	const value = read(input, name, path)
+	const value = read(input, name, at)
 	if (typeof value !== "string") {
-		throw problem([...path, name], `The field "${name}" must be a string`)
+		throw problemAt(Place.at(at, name), `The field "${name}" must be a string`)
 	}
 	return value
 }
 
-/** Reads the items of an array. */
+/** Reads the items of an array. The place of an item is `at`, `name`, index. */
 export const readList = (
 	input: unknown,
 	name: string,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 	budget: Budget,
 ): ReadonlyArray<unknown> => {
-	const value = read(input, name, path)
-	const at = [...path, name]
+	const value = read(input, name, at)
+	const place = Place.at(at, name)
 	if (!Array.isArray(value)) {
-		throw problem(at, `The field "${name}" must be an array`)
+		throw problemAt(place, `The field "${name}" must be an array`)
 	}
 	const list: ReadonlyArray<unknown> = value
-	spend(budget, list.length, at)
+	spend(budget, list.length, place)
 	// `Array.makeBy` of Effect gives at least one item, so it can not make an
 	// empty list. An array-like object with a length makes one with no read
 	// of the items before the read rule.
 	return Array.from({ length: list.length }, (_, index) =>
-		read(list, String(index), at),
+		read(list, String(index), place),
 	)
 }
 
+/**
+ * Reads a field path, and stops one with more parts than the limit of the
+ * decode. A node checks the ceiling only, since it does not know its domain.
+ */
+const readPath = (
+	input: unknown,
+	name: string,
+	at: Place.Place | undefined,
+	budget: Budget,
+): string => {
+	const path = readString(input, name, at)
+	const most = budget.limits.fieldPathParts
+	const parts = path.split(".", most + 1).length
+	if (parts > most) {
+		throw problemAt(
+			Place.at(at, name),
+			`A field path has more than ${String(most)} parts. The most is ${String(most)}.`,
+		)
+	}
+	return path
+}
+
 const isJsonScalar = (value: unknown): value is Nodes.Scalar =>
 	Nodes.isScalar(value) && (typeof value !== "number" || Number.isFinite(value))
 
 const decodeOperand = (
 	input: unknown,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
+	budget: Budget,
 ): Nodes.Operand => {
-	const tag = read(input, "_tag", path)
+	const tag = read(input, "_tag", at)
 	if (tag === "Literal") {
 		// A missing value is not `null`: a test with `null` has its own
 		// meaning, and a lost value must not become one.
@@ -113,22 +154,22 @@ const decodeOperand = (
 				? Object.getOwnPropertyDescriptor(input, "value")
 				: undefined
 		if (own === undefined || ("value" in own && own.value === undefined)) {
-			throw problem([...path, "value"], "A fixed value is missing")
+			throw problemAt(Place.at(at, "value"), "A fixed value is missing")
 		}
-		const value = read(input, "value", path)
+		const value = read(input, "value", at)
 		if (!isJsonScalar(value)) {
-			throw problem(
-				[...path, "value"],
+			throw problemAt(
+				Place.at(at, "value"),
 				"A fixed value must be a string, a finite number, a boolean or null",
 			)
 		}
 		return Nodes.literal(value)
 	}
 	if (tag === "Principal") {
-		return Nodes.principalRef(readString(input, "path", path))
+		return Nodes.principalRef(readPath(input, "path", at, budget))
 	}
-	throw problem(
-		[...path, "_tag"],
+	throw problemAt(
+		Place.at(at, "_tag"),
 		'An operand must have the tag "Literal" or "Principal"',
 	)
 }
@@ -136,96 +177,148 @@ const decodeOperand = (
 const decodeOperands = (
 	input: unknown,
 	name: string,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 	budget: Budget,
 ): ReadonlyArray<Nodes.Operand> =>
-	Arr.map(readList(input, name, path, budget), (operand, index) =>
-		decodeOperand(operand, [...path, name, index]),
+	Arr.map(readList(input, name, at, budget), (operand, index) =>
+		decodeOperand(operand, Place.at(at, name, index), budget),
 	)
 
-const decodeNode = (
-	input: unknown,
-	path: ReadonlyArray<PropertyKey>,
-	depth: number,
-	budget: Budget,
-): Node => {
-	if (depth > Limits.conditionDepth) {
-		throw problem(
-			path,
-			`A condition has more than ${String(Limits.conditionDepth)} levels. The most is ${String(Limits.conditionDepth)}.`,
-		)
-	}
-	if (typeof input !== "object" || input === null) {
-		throw problem(path, "A condition node must be an object")
-	}
-	spend(budget, 1, path)
-	const children = (name: string) =>
-		Arr.map(readList(input, name, path, budget), (child, index) =>
-			decodeNode(child, [...path, name, index], depth + 1, budget),
-		)
-	try {
-		return makeNode(input, path, depth, budget, children)
-	} catch (error) {
-		// A node past a limit, such as a field path with too many parts, is a
-		// problem at its place.
-		if (error instanceof Limits.LimitExceeded) {
-			throw problem(path, error.message)
-		}
-		throw error
-	}
+/** A part of the input to decode, with its place. */
+interface Part {
+	readonly input: unknown
+	readonly at: Place.Place | undefined
 }
 
-const makeNode = (
-	input: object,
-	path: ReadonlyArray<PropertyKey>,
-	depth: number,
-	budget: Budget,
-	children: (name: string) => ReadonlyArray<Node>,
-): Node => {
-	const tag = read(input, "_tag", path)
-	switch (tag) {
-		case "True":
-			return Nodes.always
-		case "False":
-			return Nodes.never
-		case "Compare": {
-			const op = readString(input, "op", path)
-			if (!Nodes.isCompareOperator(op)) {
-				throw problem([...path, "op"], `"${op}" is not a compare operator`)
+/**
+ * The decoder of a condition, with the budget of one decode. It is a walk of
+ * the trampoline for an input of unknown depth, so a deep input does not fill
+ * the stack.
+ */
+const decoder = (budget: Budget): ((part: Part) => Node) => {
+	// The nodes of this condition that the decoder has read. A condition with
+	// more nodes than `conditionNodes` does not load, so the decoder stops at
+	// the first node past it, and it does not read the rest of a very large
+	// input. The count belongs to the decode of one condition.
+	const count = { nodes: 0 }
+	return Trampoline.adaptive<Part, Node>((R, child) => (part, depth) => {
+		const { input, at } = part
+		if (typeof input !== "object" || input === null) {
+			throw problemAt(at, "A condition node must be an object")
+		}
+		spend(budget, 1, at)
+		count.nodes += 1
+		if (count.nodes > budget.limits.conditionNodes) {
+			throw problemAt(
+				at,
+				`A condition has more than ${String(budget.limits.conditionNodes)} nodes and values. The most is ${String(budget.limits.conditionNodes)}.`,
+			)
+		}
+		// A node past a limit, such as a field path with too many parts, is a
+		// problem at its place. The constructor checks the ceilings, and the
+		// decoder checks the limits of the decode.
+		const make = (build: () => Node): Node => {
+			const node = (() => {
+				try {
+					return build()
+				} catch (error) {
+					if (error instanceof Limits.LimitExceeded) {
+						throw problemAt(at, error.message)
+					}
+					throw error
+				}
+			})()
+			const most = budget.limits.conditionNodes
+			if (node.weight > most) {
+				throw problemAt(
+					at,
+					`A condition has ${String(node.weight)} nodes and values. The most is ${String(most)}.`,
+				)
 			}
-			return new Nodes.Compare({
-				op,
-				field: readString(input, "field", path),
-				value: decodeOperand(read(input, "value", path), [...path, "value"]),
-			})
+			return node
 		}
-		case "In":
-			return new Nodes.In({
-				field: readString(input, "field", path),
-				values: decodeOperands(input, "values", path, budget),
-			})
-		case "Exists":
-			return new Nodes.Exists({ field: readString(input, "field", path) })
-		case "Under":
-			return new Nodes.Under({
-				prefix: decodeOperands(input, "prefix", path, budget),
-			})
-		case "And":
-			return new Nodes.And(children("conditions"))
-		case "Or":
-			return new Nodes.Or(children("conditions"))
-		case "Not":
-			return new Nodes.Not(
-				decodeNode(
-					read(input, "condition", path),
-					[...path, "condition"],
-					depth + 1,
-					budget,
-				),
+		const children = (name: string) =>
+			R.forEach(readList(input, name, at, budget), (item, index) =>
+				child({ input: item, at: Place.at(at, name, index) }, depth + 1),
 			)
-		default:
-			throw problem([...path, "_tag"], "The node has no known tag")
-	}
+		const tag = read(input, "_tag", at)
+		switch (tag) {
+			case "True":
+				return R.succeed(Nodes.always)
+			case "False":
+				return R.succeed(Nodes.never)
+			case "Compare": {
+				const op = readString(input, "op", at)
+				if (!Nodes.isCompareOperator(op)) {
+					throw problemAt(
+						Place.at(at, "op"),
+						`"${op}" is not a compare operator`,
+					)
+				}
+				return R.succeed(
+					make(
+						() =>
+							new Nodes.Compare({
+								op,
+								field: readPath(input, "field", at, budget),
+								value: decodeOperand(
+									read(input, "value", at),
+									Place.at(at, "value"),
+									budget,
+								),
+							}),
+					),
+				)
+			}
+			case "In":
+				return R.succeed(
+					make(
+						() =>
+							new Nodes.In({
+								field: readPath(input, "field", at, budget),
+								values: decodeOperands(input, "values", at, budget),
+							}),
+					),
+				)
+			case "Exists":
+				return R.succeed(
+					make(
+						() =>
+							new Nodes.Exists({ field: readPath(input, "field", at, budget) }),
+					),
+				)
+			case "Under":
+				return R.succeed(
+					make(
+						() =>
+							new Nodes.Under({
+								prefix: decodeOperands(input, "prefix", at, budget),
+							}),
+					),
+				)
+			case "And":
+				return R.map(children("conditions"), (conditions) =>
+					make(() => new Nodes.And(conditions)),
+				)
+			case "Or":
+				return R.map(children("conditions"), (conditions) =>
+					make(() => new Nodes.Or(conditions)),
+				)
+			case "Not":
+				return R.map(
+					child(
+						{
+							input: read(input, "condition", at),
+							at: Place.at(at, "condition"),
+						},
+						depth + 1,
+					),
+					(condition) => make(() => new Nodes.Not(condition)),
+				)
+			default:
+				throw problemAt(Place.at(at, "_tag"), "The node has no known tag")
+		}
+	})
 }
 
 /**
@@ -234,14 +327,16 @@ const makeNode = (
  */
 export const decodeAt = (
 	input: unknown,
-	path: ReadonlyArray<PropertyKey>,
+	at: Place.Place | undefined,
 	budget: Budget,
-): Node => decodeNode(input, path, 1, budget)
+): Node => decoder(budget)({ input, at })
 
-/** Decodes the JSON form of a condition. */
+/** Decodes the JSON form of a condition, with the default limits. */
 export const decode = (input: unknown): Result.Result<Node, Problem> => {
 	try {
-		return Result.succeed(decodeNode(input, [], 1, { used: 0 }))
+		return Result.succeed(
+			decoder({ used: 0, limits: Limits.defaults })({ input, at: undefined }),
+		)
 	} catch (error) {
 		if (error instanceof Problem) {
 			return Result.fail(error)

package/src/internal/limits.ts

@@ -1,50 +1,120 @@
 /**
  * The one table of limits. Each limit keeps a walk, a decoder or a search
- * bounded, so no input can fill the stack or take a very long time. The
- * values are the same in the types and at run time where both have one, as
- * for the parts of a field path.
+ * bounded, so no input can take a very long time or very much memory. A
+ * domain may set its own limits, up to the ceilings.
  */
 import * as Schema from "effect/Schema"
 
-/** The most parts of a field path, as in `settings.model`. */
-export const fieldPathParts = 5
-
-/** The most parts of a field pattern, as in `**.secret`. */
-export const patternParts = 16
+/** The values of all the limits. */
+export interface Limits {
+	/** The most parts of a field path, as in `settings.model`. */
+	readonly fieldPathParts: number
+	/** The most parts of a field pattern, as in `**.secret`. */
+	readonly patternParts: number
+	/**
+	 * The most nodes of one condition. A child that a condition uses in many
+	 * places is counted for each place.
+	 */
+	readonly conditionNodes: number
+	/** The most nodes of one residual condition. */
+	readonly residualNodes: number
+	/**
+	 * The most nodes of a policy tree, with its rules and the nodes of their
+	 * conditions. A part that the tree uses in many places is counted for
+	 * each place.
+	 */
+	readonly policyNodes: number
+	/** The most objects and arrays in one input to a decoder. */
+	readonly jsonNodes: number
+	/** The most fields in the list of the fields of one Schema. */
+	readonly catalogFields: number
+	/** The most steps of one search for a value. */
+	readonly searchSteps: number
+	/** The most fields that one search for a value may test. */
+	readonly searchFields: number
+}
 
 /**
- * The most nodes of one condition. A child that a condition uses in many
- * places is counted for each place.
+ * The limits of a domain that sets none. A walk does not fill the stack at
+ * any depth (see `Trampoline`), and the levels of a condition or of a policy
+ * tree are at most its nodes, so the limits of the nodes keep the time and
+ * the memory of a deep input small too. There is no limit of levels.
  */
-export const conditionNodes = 100_000
-
-/** The most levels of one condition. */
-export const conditionDepth = 500
+export const defaults: Limits = {
+	fieldPathParts: 1000,
+	patternParts: 1000,
+	conditionNodes: 1_000_000,
+	residualNodes: 100_000,
+	policyNodes: 1_000_000,
+	jsonNodes: 10_000_000,
+	catalogFields: 100_000,
+	// A search is the work of one check of a kind, as in the Authorizer, so
+	// its steps are a limit of the time of one request.
+	searchSteps: 1_000_000,
+	searchFields: 1000,
+}
 
-/** The most nodes of one residual condition. */
-export const residualNodes = 10_000
+/**
+ * The most that a domain may set for each limit. The constructors of the
+ * nodes check these, since a node does not know its domain. The binding to a
+ * domain checks the limits of the domain.
+ */
+export const ceilings: Limits = {
+	fieldPathParts: 10_000,
+	patternParts: 10_000,
+	conditionNodes: 100_000_000,
+	residualNodes: 100_000_000,
+	policyNodes: 100_000_000,
+	jsonNodes: 1_000_000_000,
+	catalogFields: 10_000_000,
+	searchSteps: 1_000_000_000,
+	searchFields: 100_000,
+}
 
-/** The most levels of a policy tree. */
-export const policyDepth = 256
+/** The Schema of one limit: a whole number from 1 up to its ceiling. */
+const limit = (name: keyof Limits) =>
+	Schema.optionalKey(
+		Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: ceilings[name] })),
+	)
 
 /**
- * The most nodes of a policy tree, with its rules and the nodes of their
- * conditions. A part that the tree uses in many places is counted for each
- * place.
+ * The Schema of the limits that a domain sets. Each one is a whole number
+ * from 1 up to its ceiling, and a limit that the domain leaves out has its
+ * default.
  */
-export const policyNodes = 100_000
+export const Options = Schema.Struct({
+	fieldPathParts: limit("fieldPathParts"),
+	patternParts: limit("patternParts"),
+	conditionNodes: limit("conditionNodes"),
+	residualNodes: limit("residualNodes"),
+	policyNodes: limit("policyNodes"),
+	jsonNodes: limit("jsonNodes"),
+	catalogFields: limit("catalogFields"),
+	searchSteps: limit("searchSteps"),
+	searchFields: limit("searchFields"),
+})
 
-/** The most objects and arrays in one input to a decoder. */
-export const jsonNodes = 1_000_000
-
-/** The most fields in the catalog of one Schema. */
-export const catalogFields = 10_000
+/**
+ * Makes the limits of a domain from the ones that it sets. A value that is
+ * not a whole number from 1 up to its ceiling is a mistake in the code, so
+ * it is a defect.
+ */
+export const make = (options: unknown = {}): Limits => ({
+	...defaults,
+	...Schema.decodeUnknownSync(Options)(options),
+})
 
-/** The most steps of one search for a value. */
-export const searchSteps = 1_000_000
+// The default of each limit, by its name.
 
-/** The most fields that one search for a value may test. */
-export const searchFields = 256
+export const fieldPathParts = defaults.fieldPathParts
+export const patternParts = defaults.patternParts
+export const conditionNodes = defaults.conditionNodes
+export const residualNodes = defaults.residualNodes
+export const policyNodes = defaults.policyNodes
+export const jsonNodes = defaults.jsonNodes
+export const catalogFields = defaults.catalogFields
+export const searchSteps = defaults.searchSteps
+export const searchFields = defaults.searchFields
 
 /**
  * The error when an input goes past a limit. It names the limit, the size of