🥮 mooncakes.io

moon-problem-details

RFC 9457 Problem Details JSON parser, serializer, validator, registry and audit toolkit for MoonBit.

problem-details
rfc9457
http
api
json
error
moonbit
moon add 6P66006/moon-problem-details@0.1.0-dev
Download zip
Author
Version
0.1.0-dev
License
Apache-2.0
Repository
Last updated
4 days ago
Downloads
1
README

#moon-problem-details

Module: 6P66006/moon-problem-details Version: 0.1.0-dev Status: public mature MVP Repository: https://github.com/6P66006/moon-problem-details Maintainer: 崔瑞豪 (3911798739@qq.com)

#Overview

moon-problem-details is an offline MoonBit toolkit for RFC 9457 Problem Details JSON. It parses, preserves, builds, validates, canonicalizes, audits and queries registered HTTP problem types without sending HTTP requests or dereferencing URIs.

#Quick start

Check the package and run the parsing example from the repository root:

moon check --target wasm-gc
moon run ./examples/parse --target wasm-gc

For a complete cross-target verification, including tests and CLI smoke checks, run ./scripts/verify_all.ps1.

#Why Problem Details

Problem Details gives HTTP APIs a shared error-document shape while allowing each problem type to define extension members. This library keeps transport status separate: the JSON status member is advisory and never replaces the actual HTTP response status.

#RFC 9457 scope

The mature local MVP covers application/problem+json, the five standard members, extension members, about:blank, URI-reference syntax checks, deterministic serialization, HTTP response context checking, resource limits, structured errors and an offline IANA registry. RFC 9457, which obsoletes RFC 7807, is the implementation target.

#Problem model

ProblemDetails keeps type, title, status, detail and instance optional exactly as received. effective_type() returns about:blank when raw type is absent without modifying the parsed model.

#Parsing

Use parse_problem_json for text or parse_problem_json_bytes for raw UTF-8. MoonBit core parses JSON. A malformed JSON document or non-object root is a structured error. A standard member with the wrong JSON type is ignored and reported in ProblemParseResult.diagnostics, so other members continue to parse as RFC 9457 requires.

#Standard and extension members

Unknown object members are preserved as arbitrary Json values, including strings, numbers, booleans, nulls, arrays and objects. extension, extensions and has_extension query them. Builder extensions cannot collide with standard member names.

#about:blank

Missing type has the effective value about:blank. is_about_blank handles both missing and explicit forms. A nonstandard title for about:blank is an audit warning only because localization is permitted.

#Validation and HTTP context

validate_problem checks URI-reference syntax and the HTTP status range. validate_context checks application/problem+json, status mismatch and whether relative type or instance values have an absolute base URI. The caller supplies context; the library has no server or client.

#Building and serialization

ProblemBuilder::new() supports fluent standard members and arbitrary JSON extensions. problem(status, title) and about_blank(status) are conveniences. serialize_problem emits standard members in type, title, status, detail, instance order and top-level extensions in code-unit lexical order. Object order has no JSON semantics; ordering exists only for reproducibility.

#IANA registry

The vendored official HTTP Problem Types CSV is queried through is_registered_problem_type, lookup_problem_type and registered_problem_types. Runtime operation is entirely offline. The refresh script contacts IANA only with explicit --refresh; verification checks SHA-256, record count and generated data freshness.

Verify the committed snapshot without network access:

python ./scripts/verify_iana_snapshot.py

Maintainers may explicitly download a newer official CSV with python ./scripts/import_iana_problem_types.py --refresh. After reviewing the registry changes, regenerate generated_problem_types.mbt, update the recorded metadata and rerun the offline verifier. Normal builds, tests and CLI commands never invoke the refresh path.

#Audit and security

audit_problem reports advisory findings such as relative URIs, suspicious extension names, missing members, overlong text and debug-looking names. It is heuristic, not a sensitive-data detector. Do not put passwords, tokens, secrets, stack traces, SQL, server paths, internal hosts or private user data in titles, details or extensions.

#CLI

problem-tool provides exactly these commands: parse, validate, canonicalize, make, registry, audit, stats, plus version and help. All commands are offline and emit deterministic JSON where practical.

moon run ./cmd/problem-tool -- parse --input '{"status":404}'
moon run ./cmd/problem-tool -- validate --status 404 --input '{"status":404}'
moon run ./cmd/problem-tool -- registry about:blank
moon run ./cmd/problem-tool -- make --status 404 --title "Not Found"

Wrongly typed standard members are ignored with diagnostics instead of aborting the document:

moon run ./cmd/problem-tool -- parse --input '{"title":123,"status":404,"request_id":"abc"}'

The result retains status and request_id, omits the invalid title, and reports one diagnostic.

#Examples and testing

Four executable examples under examples/ demonstrate parsing, building, validation and audit. Tests cover RFC-style fixtures, wrong-type member behavior, extensions, limits, the registry, 800 deterministic property cases and every byte prefix of complex UTF-8 documents. Run the fail-fast gate with:

.\scripts\verify_all.ps1

It formats, checks and tests wasm-gc, JS and native; smoke-tests every CLI command and example; verifies the snapshot; counts code; and lists the package.

#Limitations

No application/problem+xml, XML, HTTP server/client, automatic URI dereference, full RFC 3986 resolver, JSON Schema, OpenAPI, exception framework or sensitive-data guarantee. See docs/limitations.md.

#License and local development status

Apache-2.0. The source repository is public on GitHub. The module remains a development version and has not been published to Mooncakes.

#
ProblemError

source
pub(all) suberror ProblemError {
  ProblemError(ProblemErrorStage, ProblemErrorKind, String, Int?)
}

A structured error. JSON parser offsets are not invented when unavailable.

#
ProblemError::byte_offset

source
fn ProblemError::byte_offset(self : ProblemError) -> Int?

#
ProblemError::context

source
fn ProblemError::context(self : ProblemError) -> String

#
ProblemError::kind

source

#
ProblemError::stage

source

#
ProblemError::to_string

source
fn ProblemError::to_string(self : ProblemError) -> String

#
AuditIssue

source
pub struct AuditIssue {
  kind : AuditIssueKind
  severity : AuditSeverity
  context : String
} derive(Eq, 
Debug)

#
AuditIssue::context

source
fn AuditIssue::context(self : AuditIssue) -> String

#
AuditIssue::kind

source

#
AuditIssue::severity

source
fn AuditIssue::severity(self : AuditIssue) -> AuditSeverity

#
AuditIssueKind

source
pub(all) enum AuditIssueKind {
  RelativeTypeUri
  RelativeInstanceUri
  SuspiciousExtensionName
  OverlongTitle
  OverlongDetail
  AboutBlankTitleMismatch
  MissingTitle
  MissingStatus
  SensitiveLookingExtension
  DebugInformationRisk
} derive(Eq, 
Debug)

Audit advice and heuristics; these are not parser errors.

#
AuditIssueKind::name

source
fn AuditIssueKind::name(self : AuditIssueKind) -> String

#
AuditReport

source
pub struct AuditReport {
  issues : Array[AuditIssue]
} derive(Eq, 
Debug)

#
AuditReport::is_clean

source
fn AuditReport::is_clean(self : AuditReport) -> Bool

#
AuditReport::issues

source
fn AuditReport::issues(self : AuditReport) -> Array[AuditIssue]

#
AuditSeverity

source
pub(all) enum AuditSeverity {
  Info
  Warning
} derive(Eq, 
Debug)

#
ContextIssue

source
pub struct ContextIssue {
  kind : ContextIssueKind
  context : String
} derive(Eq, 
Debug)

#
ContextIssue::context

source
fn ContextIssue::context(self : ContextIssue) -> String

#
ContextIssue::kind

source

#
ContextIssueKind

source
pub(all) enum ContextIssueKind {
  InvalidContentType
  StatusMismatch
  MissingBaseUri
  InvalidBaseUri
} derive(Eq, 
Debug)

#
ContextIssueKind::name

source
fn ContextIssueKind::name(self : ContextIssueKind) -> String

#
ExtensionMember

source
pub struct ExtensionMember {
  name : String
  value : Json
} derive(Eq, 
Debug)

One extension member. Its value is any JSON value, without coercion.

#
ExtensionMember::name

source
fn ExtensionMember::name(self : ExtensionMember) -> String

#
ExtensionMember::value

source
fn ExtensionMember::value(self : ExtensionMember) -> Json

#
Limits

source
pub struct Limits {
  max_input_bytes : Int
  max_members : Int
  max_extension_members : Int
  max_string_bytes : Int
  max_title_bytes : Int
  max_detail_bytes : Int
  max_nesting_depth : Int
} derive(Eq, 
Debug)

Parser and traversal resource limits.

#
Limits::default

source
fn Limits::default() -> Limits

#
Limits::max_detail_bytes

source
fn Limits::max_detail_bytes(self : Limits) -> Int

#
Limits::max_extension_members

source
fn Limits::max_extension_members(self : Limits) -> Int

#
Limits::max_input_bytes

source
fn Limits::max_input_bytes(self : Limits) -> Int

#
Limits::max_members

source
fn Limits::max_members(self : Limits) -> Int

#
Limits::max_nesting_depth

source
fn Limits::max_nesting_depth(self : Limits) -> Int

#
Limits::max_string_bytes

source
fn Limits::max_string_bytes(self : Limits) -> Int

#
Limits::max_title_bytes

source
fn Limits::max_title_bytes(self : Limits) -> Int

#
Limits::permissive

source
fn Limits::permissive() -> Limits

#
Limits::strict

source
fn Limits::strict() -> Limits

#
ProblemBuilder

source
pub struct ProblemBuilder {
  type_raw : String?
  title : String?
  status : Int?
  detail : String?
  instance : String?
  extensions : Array[ExtensionMember]
  error : ProblemError?
}

Mutable fluent builder. Build returns a structured error on invalid state.

#
ProblemBuilder::build

source

#
ProblemBuilder::detail

source
fn ProblemBuilder::detail(self : ProblemBuilder, value : String) -> ProblemBuilder

#
ProblemBuilder::extension

source
fn ProblemBuilder::extension(self : ProblemBuilder, name : String, value : Json) -> ProblemBuilder

#
ProblemBuilder::instance

source
fn ProblemBuilder::instance(self : ProblemBuilder, value : String) -> ProblemBuilder

#
ProblemBuilder::new

source

#
ProblemBuilder::status

source
fn ProblemBuilder::status(self : ProblemBuilder, value : Int) -> ProblemBuilder

#
ProblemBuilder::title

source
fn ProblemBuilder::title(self : ProblemBuilder, value : String) -> ProblemBuilder

#
ProblemBuilder::type_uri

source
fn ProblemBuilder::type_uri(self : ProblemBuilder, value : String) -> ProblemBuilder

#
ProblemContext

source
pub struct ProblemContext {
  actual_status : Int?
  content_type : String?
  base_uri : String?
} derive(Eq, 
Debug)

HTTP response metadata supplied by the caller; this library sends no HTTP.

#
ProblemDetails

source
pub struct ProblemDetails {
  type_raw : String?
  title : String?
  status : Int?
  detail : String?
  instance : String?
  extensions : Array[ExtensionMember]
} derive(Eq, 
Debug)

RFC 9457 Problem Details data model. Missing members remain missing.

#
ProblemDetails::detail

source
fn ProblemDetails::detail(self : ProblemDetails) -> String?

#
ProblemDetails::effective_type

source
fn ProblemDetails::effective_type(self : ProblemDetails) -> String

Missing type is semantically about:blank; parsing does not insert it.

#
ProblemDetails::extension

source
fn ProblemDetails::extension(self : ProblemDetails, name : String) -> Json?

#
ProblemDetails::extensions

source

#
ProblemDetails::has_extension

source
fn ProblemDetails::has_extension(self : ProblemDetails, name : String) -> Bool

#
ProblemDetails::instance

source
fn ProblemDetails::instance(self : ProblemDetails) -> String?

#
ProblemDetails::is_about_blank

source
fn ProblemDetails::is_about_blank(self : ProblemDetails) -> Bool

#
ProblemDetails::member_count

source
fn ProblemDetails::member_count(self : ProblemDetails) -> Int

#
ProblemDetails::standard_member_count

source
fn ProblemDetails::standard_member_count(self : ProblemDetails) -> Int

#
ProblemDetails::status

source
fn ProblemDetails::status(self : ProblemDetails) -> Int?

#
ProblemDetails::title

source
fn ProblemDetails::title(self : ProblemDetails) -> String?

#
ProblemDetails::type_raw

source
fn ProblemDetails::type_raw(self : ProblemDetails) -> String?

#
ProblemDiagnostic

source
pub struct ProblemDiagnostic {
  kind : ProblemDiagnosticKind
  member_name : String
  expected : String
  actual : String
} derive(Eq, 
Debug)

#
ProblemDiagnostic::actual

source
fn ProblemDiagnostic::actual(self : ProblemDiagnostic) -> String

#
ProblemDiagnostic::expected

source
fn ProblemDiagnostic::expected(self : ProblemDiagnostic) -> String

#
ProblemDiagnostic::kind

source

#
ProblemDiagnostic::member_name

source
fn ProblemDiagnostic::member_name(self : ProblemDiagnostic) -> String

#
ProblemDiagnosticKind

source
pub(all) enum ProblemDiagnosticKind {
  IgnoredMemberWrongType
} derive(Eq, 
Debug)

Non-fatal interpretation diagnostic required by RFC 9457 consumer semantics.

#
ProblemErrorKind

source
pub(all) enum ProblemErrorKind {
  InvalidJson
  InvalidUtf8
  RootNotObject
  InvalidUriReference
  InvalidPercentEncoding
  InvalidStatus
  DuplicateReservedExtension
  LimitExceeded
  InvalidBuilderState
} derive(Eq, 
Debug)

Machine-readable error category.

#
ProblemErrorKind::name

source
fn ProblemErrorKind::name(self : ProblemErrorKind) -> String

#
ProblemErrorStage

source
pub(all) enum ProblemErrorStage {
  Input
  Json
  Member
  Uri
  Status
  Limit
  Registry
  Builder
  Context
} derive(Eq, 
Debug)

Structured processing stage for errors.

#
ProblemErrorStage::name

source
fn ProblemErrorStage::name(self : ProblemErrorStage) -> String

#
ProblemParseResult

source
pub struct ProblemParseResult {
  problem : ProblemDetails
  diagnostics : Array[ProblemDiagnostic]
} derive(Eq, 
Debug)

Successful parse plus non-fatal diagnostics.

#
ProblemParseResult::diagnostics

source

#
ProblemParseResult::problem

source

#
ProblemTypeRecord

source
pub struct ProblemTypeRecord {
  type_uri : String
  title : String
  recommended_status : Int?
  reference : String
} derive(Eq, 
Debug)

One offline IANA HTTP Problem Types registration.

#
ProblemTypeRecord::recommended_status

source
fn ProblemTypeRecord::recommended_status(self : ProblemTypeRecord) -> Int?

#
ProblemTypeRecord::reference

source
fn ProblemTypeRecord::reference(self : ProblemTypeRecord) -> String

#
ProblemTypeRecord::title

source
fn ProblemTypeRecord::title(self : ProblemTypeRecord) -> String

#
ProblemTypeRecord::type_uri

source
fn ProblemTypeRecord::type_uri(self : ProblemTypeRecord) -> String

#
UriReferenceInfo

source
pub struct UriReferenceInfo {
  absolute : Bool
  relative : Bool
} derive(Eq, 
Debug)

Result of the intentionally small RFC 3986 URI-reference syntax check.

#
UriReferenceInfo::is_absolute

source
fn UriReferenceInfo::is_absolute(self : UriReferenceInfo) -> Bool

#
UriReferenceInfo::is_relative

source
fn UriReferenceInfo::is_relative(self : UriReferenceInfo) -> Bool

#
ValidationIssue

source
pub struct ValidationIssue {
  kind : ValidationIssueKind
  context : String
} derive(Eq, 
Debug)

#
ValidationIssue::context

source
fn ValidationIssue::context(self : ValidationIssue) -> String

#
ValidationIssue::kind

source

#
ValidationIssueKind

source
pub(all) enum ValidationIssueKind {
  InvalidTypeUri
  InvalidInstanceUri
  InvalidStatusCode
} derive(Eq, 
Debug)

Hard, objectively verifiable semantic issue.

#
ValidationIssueKind::name

source
fn ValidationIssueKind::name(self : ValidationIssueKind) -> String

#
about_blank

source
fn about_blank(status : Int) -> Result[ProblemDetails, ProblemError]

#
audit_problem

source
fn audit_problem(problem : ProblemDetails) -> AuditReport

Heuristic security and interoperability audit. It makes no leak-detection guarantee.

#
canonicalize_problem_json

source
fn canonicalize_problem_json(input : String) -> Result[String, ProblemError]

#
extension_member

source
fn extension_member(name : String, value : Json) -> ExtensionMember

#
is_absolute_uri_reference

source
fn is_absolute_uri_reference(value : String) -> Bool

#
is_registered_problem_type

source
fn is_registered_problem_type(uri : String) -> Bool

#
is_valid_http_status

source
fn is_valid_http_status(code : Int) -> Bool

#
is_valid_problem

source
fn is_valid_problem(problem : ProblemDetails) -> Bool

#
library_version

source
fn library_version() -> String

#
lookup_problem_type

source
fn lookup_problem_type(uri : String) -> ProblemTypeRecord?

#
parse_problem

source
fn parse_problem(input : String) -> Result[ProblemDetails, ProblemError]

Convenience API preserving errors while discarding diagnostics.

#
parse_problem_json

source
fn parse_problem_json(input : String) -> Result[ProblemParseResult, ProblemError]

#
parse_problem_json_bytes

source
fn parse_problem_json_bytes(input : Bytes, limits? : Limits) -> Result[ProblemParseResult, ProblemError]

Byte-oriented entry point for network payloads and truncation testing.

#
parse_problem_json_with_limits

source
fn parse_problem_json_with_limits(input : String, limits : Limits) -> Result[ProblemParseResult, ProblemError]

Parse JSON using core's parser, then interpret RFC 9457 members.

#
problem

source
fn problem(status : Int, title : String) -> Result[ProblemDetails, ProblemError]

#
problem_context

source
fn problem_context(actual_status : Int?, content_type : String?, base_uri : String?) -> ProblemContext

#
problem_details

source
fn problem_details(type_raw : String?, title : String?, status : Int?, detail : String?, instance : String?, extensions : Array[ExtensionMember]) -> ProblemDetails

#
problem_error

source
fn problem_error(stage : ProblemErrorStage, kind : ProblemErrorKind, context : String, byte_offset? : Int) -> ProblemError

#
problem_media_type

source
fn problem_media_type() -> String

#
problem_type_record

source
fn problem_type_record(type_uri : String, title : String, recommended_status : Int?, reference : String) -> ProblemTypeRecord

#
registered_problem_types

source
fn registered_problem_types() -> Array[ProblemTypeRecord]

#
registry_snapshot_date

source
fn registry_snapshot_date() -> String

#
registry_snapshot_sha256

source
fn registry_snapshot_sha256() -> String

#
serialize_problem

source
fn serialize_problem(problem : ProblemDetails) -> String

Deterministic top-level serializer: RFC members first, extensions sorted.

#
status_reason

source
fn status_reason(code : Int) -> String?

Common HTTP reason phrases. Unknown valid status codes return None.

#
validate_context

source
fn validate_context(problem : ProblemDetails, context : ProblemContext) -> Array[ContextIssue]

#
validate_problem

source
fn validate_problem(problem : ProblemDetails) -> Array[ValidationIssue]

Validate semantic constraints separately from parsing and audit advice.

#
validate_uri_reference

source
fn validate_uri_reference(value : String) -> Result[UriReferenceInfo, ProblemError]

Validate the syntax needed by RFC 9457 without resolving or dereferencing.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io