🥮 mooncakes.io

acceptkit

Dependency-free HTTP representation negotiation toolkit for MoonBit.

http
accept
content-negotiation
headers
wasm
moon add XiaoMao-MYY/acceptkit@0.1.0
Download zip
Version
0.1.0
License
MIT
Repository
Last updated
8 days ago
Downloads
2
README

#acceptkit

acceptkit 是一个 MoonBit 原生、无外部依赖的 HTTP 表示协商工具库，用于解析 Accept、Accept-Language、Accept-Encoding、Accept-Charset、Vary、Cache-Control 和 ETag 条件请求相关头，并为服务端候选响应选择最合适的表示。

它解决的问题是：MoonBit Web 服务、Wasm HTTP 组件、接口 Mock、边缘函数和测试工具经常需要处理内容协商，但直接手写字符串判断容易漏掉 q 权重、通配符、显式拒绝、参数匹配、稳定排序、响应头生成和缓存相关边界。acceptkit 提供结构化解析结果、确定性的协商算法、候选矩阵和可读解释文本，便于在库、工具和示例工程中复用。

#适用场景

  • HTTP 服务端根据 Accept 选择 application/json、text/html、application/problem+json 等响应格式；
  • API 工具或 Mock 服务根据 Accept-Language 选择本地化语言；
  • 服务端根据 Accept-Encoding 选择 br、gzip 或 identity；
  • 服务端根据 Accept-Charset 选择 utf-8、iso-8859-1 等字符集；
  • Web 框架中间件生成 Content-Type、Content-Language、Content-Encoding 和 Vary；
  • 测试工具记录候选矩阵，解释“为什么选择该响应格式”；
  • 缓存层检查 Cache-Control、Vary 和 ETag 条件请求行为。

#安装

moon add XiaoMao-MYY/acceptkit

Mooncakes 包名：

XiaoMao-MYY/acceptkit

#最小使用示例

在使用方 moon.pkg 中导入：

import {
  "XiaoMao-MYY/acceptkit" @acceptkit,
}

MoonBit 代码：

fn choose() -> String {
  let result = @acceptkit.negotiate_response(
    @acceptkit.RequestPreferences(
      accept="application/json, text/html;q=0.6",
      accept_language="zh-CN, en;q=0.8",
      accept_encoding="br, gzip;q=0.7",
      accept_charset="utf-8",
    ),
    ["text/html", "application/json"],
    ["en-US", "zh-CN"],
    ["gzip", "br"],
    ["utf-8"],
  )
  match result {
    Ok(choice) => @acceptkit.response_header_block(choice.summary)
    Err(_) => "invalid negotiation header"
  }
}

#本地运行

moon check
moon build
moon test
moon run cmd/main

示例入口会输出媒体类型协商、语言协商、组合响应协商和响应头结果。

#核心 API

  • parse_accept(header)：解析 Accept 头，返回 MediaRange 列表；
  • parse_content_type(value)：解析服务端候选媒体类型，返回 MediaOffer；
  • negotiate_media(header, offers)：在候选媒体类型中选择最佳结果；
  • parse_accept_language(header)、negotiate_language(header, offers)：解析语言偏好并选择语言；
  • parse_accept_encoding(header)、negotiate_encoding(header, offers)：解析压缩编码偏好并选择编码；
  • parse_accept_charset(header)、negotiate_charset(header, offers)：解析字符集偏好并选择字符集；
  • ServerVariant、negotiate_variant(preferences, variants)：对媒体、语言、编码、字符集和服务端权重做组合协商；
  • build_response_variants(...)、negotiate_response(...)：从常见服务端候选数组生成变体并返回响应摘要；
  • response_headers(summary)、response_header_block(summary)：生成响应头；
  • parse_vary(value)、merge_vary(left, right)：解析、规范化和合并 Vary；
  • parse_cache_policy(header)、format_cache_summary(summary)：提取缓存策略摘要；
  • parse_etag(value)、evaluate_if_none_match(method, header, current)、evaluate_if_match(header, current)：处理 ETag 条件请求；
  • audit_preferences(preferences)、audit_cache_control_header(header)：输出可检查的风险提示；
  • negotiation_matrix_report(preferences, variants)：生成候选矩阵报告。

#支持范围

  • Accept 中的 type/subtype、type/*、*/*；
  • 媒体类型参数匹配，例如 text/html;level=1；
  • q 权重，使用 0 到 1000 的整数表示，支持三位小数；
  • q=0 显式拒绝，且拒绝会优先于通配符回退；
  • 引号包裹的参数值，分割时会避开引号内的逗号和分号；
  • Accept-Language 基础语言范围、通配符和前缀匹配；
  • Accept-Encoding 的通配符、identity 默认可接受语义和显式拒绝；
  • Accept-Charset 常见别名规范化，例如 utf8、latin1、us_ascii；
  • 组合变体协商、响应摘要、响应头生成和 406 摘要；
  • Vary 规范化、合并和缓存键风险审计；
  • Cache-Control 常见缓存指令摘要；
  • 强/弱 ETag 解析和 If-None-Match、If-Match 判断；
  • 稳定排序：权重、具体度、参数数量、头部顺序、服务端权重、候选顺序。

#边界

  • 不解析完整 HTTP 报文；
  • 不做网络 I/O、文件 I/O 或框架绑定；
  • 不查询媒体类型注册表；
  • 不实现完整自然语言回退策略；
  • 不包含压缩、字符集转码或缓存存储实现。

#测试与验收命令

moon check
moon build
moon test
moon run cmd/main
moon publish --dry-run

#开源许可证和第三方说明

本项目采用 MIT License。核心实现为原创 MoonBit 代码，不移植第三方源码，不包含第三方素材。实现语义参考 HTTP 内容协商常见规则和 RFC 系列标准描述。

#
CacheDirective

source
pub(all) struct CacheDirective {
  name : String
  value : String?
  order : Int
  raw : String
} derive(Eq, 
Debug)

#
CachePolicySummary

source
pub(all) struct CachePolicySummary {
  no_store : Bool
  no_cache : Bool
  is_public : Bool
  is_private : Bool
  must_revalidate : Bool
  immutable : Bool
  max_age : Int?
  s_maxage : Int?
  stale_while_revalidate : Int?
  stale_if_error : Int?
  unknown : Array[CacheDirective]
} derive(Eq, 
Debug)

#
CharsetCandidate

source
pub(all) struct CharsetCandidate {
  offer : CharsetOffer
  matched_range : CharsetRange
  quality : Int
  specificity : Int
  reason : String
} derive(Eq, 
Debug)

#
CharsetDecision

source
pub(all) struct CharsetDecision {
  selected : String?
  quality : Int
  candidate : CharsetCandidate?
  matches : Array[CharsetCandidate]
  explanation : String
} derive(Eq, 
Debug)

#
CharsetOffer

source
pub(all) struct CharsetOffer {
  charset : String
  canonical : String
  index : Int
} derive(Eq, 
Debug)

#
CharsetRange

source
pub(all) struct CharsetRange {
  charset : String
  q : Int
  order : Int
  raw : String
} derive(Eq, 
Debug)

#
ConditionalDecision

source
pub(all) struct ConditionalDecision {
  matched : Bool
  status : Int
  reason : String
} derive(Eq, 
Debug)

#
EncodingCandidate

source
pub(all) struct EncodingCandidate {
  offer : EncodingOffer
  matched_range : EncodingRange
  quality : Int
  specificity : Int
  reason : String
} derive(Eq, 
Debug)

#
EncodingDecision

source
pub(all) struct EncodingDecision {
  selected : String?
  quality : Int
  candidate : EncodingCandidate?
  matches : Array[EncodingCandidate]
  explanation : String
} derive(Eq, 
Debug)

#
EncodingOffer

source
pub(all) struct EncodingOffer {
  coding : String
  index : Int
} derive(Eq, 
Debug)

#
EncodingRange

source
pub(all) struct EncodingRange {
  coding : String
  q : Int
  order : Int
  raw : String
} derive(Eq, 
Debug)

#
EntityTag

source
pub(all) struct EntityTag {
  weak : Bool
  tag : String
  raw : String
} derive(Eq, 
Debug)

#
HeaderAudit

source
pub(all) struct HeaderAudit {
  ok : Bool
  warnings : Array[String]
  errors : Array[String]
} derive(Eq, 
Debug)

#
LanguageCandidate

source
pub(all) struct LanguageCandidate {
  offer : LanguageOffer
  matched_range : LanguageRange
  quality : Int
  specificity : Int
  reason : String
} derive(Eq, 
Debug)

#
LanguageDecision

source
pub(all) struct LanguageDecision {
  selected : String?
  quality : Int
  candidate : LanguageCandidate?
  matches : Array[LanguageCandidate]
  explanation : String
} derive(Eq, 
Debug)

#
LanguageOffer

source
pub(all) struct LanguageOffer {
  tag : String
  primary : String
  subtags : Array[String]
  index : Int
} derive(Eq, 
Debug)

#
LanguageRange

source
pub(all) struct LanguageRange {
  primary : String
  subtags : Array[String]
  q : Int
  order : Int
  raw : String
} derive(Eq, 
Debug)

#
MediaCandidate

source
pub(all) struct MediaCandidate {
  offer : MediaOffer
  matched_range : MediaRange
  quality : Int
  specificity : Int
  parameter_matches : Int
  reason : String
} derive(Eq, 
Debug)

#
MediaDecision

source
pub(all) struct MediaDecision {
  selected : String?
  quality : Int
  candidate : MediaCandidate?
  matches : Array[MediaCandidate]
  explanation : String
} derive(Eq, 
Debug)

#
MediaOffer

source
pub(all) struct MediaOffer {
  value : String
  top : String
  sub : String
  params : Array[Param]
  index : Int
} derive(Eq, 
Debug)

#
MediaRange

source
pub(all) struct MediaRange {
  top : String
  sub : String
  params : Array[Param]
  extensions : Array[Param]
  q : Int
  order : Int
  raw : String
} derive(Eq, 
Debug)

#
Param

source
pub(all) struct Param {
  name : String
  value : String
} derive(Eq, 
Debug)

#
ParseError

source
pub(all) enum ParseError {
  EmptyItem(Int)
  MissingSlash(Int, String)
  InvalidToken(Int, String, String)
  InvalidParameter(Int, String)
  InvalidQ(Int, String)
  InvalidWildcard(Int, String)
  InvalidOffer(Int, String)
  InvalidLanguageTag(Int, String)
} derive(Eq, 
Debug)

#
RequestPreferences

source
pub(all) struct RequestPreferences {
  accept : String
  accept_language : String
  accept_encoding : String
  accept_charset : String
} derive(Eq, 
Debug)

#
RequestPreferences::RequestPreferences

source
fn RequestPreferences::RequestPreferences(accept? : StringView, accept_language? : StringView, accept_encoding? : StringView, accept_charset? : StringView) -> RequestPreferences

#
ResponseNegotiation

source
pub(all) struct ResponseNegotiation {
  decision : VariantDecision
  summary : ResponseSummary
  headers : Array[Param]
  header_block : String
} derive(Eq, 
Debug)

#
ResponseSummary

source
pub(all) struct ResponseSummary {
  status : Int
  content_type : String?
  content_language : String?
  content_encoding : String?
  charset : String?
  vary : Array[String]
  explanation : String
} derive(Eq, 
Debug)

#
ServerVariant

source
pub(all) struct ServerVariant {
  id : String
  media : String
  language : String?
  encoding : String?
  charset : String?
  server_weight : Int
  index : Int
} derive(Eq, 
Debug)

#
ServerVariant::ServerVariant

source
fn ServerVariant::ServerVariant(id : StringView, media : StringView, language? : StringView, encoding? : StringView, charset? : StringView, server_weight? : Int, index? : Int) -> ServerVariant

#
VariantCandidate

source
pub(all) struct VariantCandidate {
  variant : ServerVariant
  media : MediaCandidate?
  language : LanguageCandidate?
  encoding : EncodingCandidate?
  charset : CharsetCandidate?
  quality : Int
  reason : String
} derive(Eq, 
Debug)

#
VariantDecision

source
pub(all) struct VariantDecision {
  selected : ServerVariant?
  quality : Int
  matches : Array[VariantCandidate]
  vary : Array[String]
  explanation : String
} derive(Eq, 
Debug)

#
api_preferences_json_zh_gzip

source
fn api_preferences_json_zh_gzip() -> RequestPreferences

#
api_response_summary

source
fn api_response_summary() -> Result[ResponseSummary, ParseError]

#
api_variants

source
fn api_variants() -> Array[ServerVariant]

#
audit_accept

source
fn audit_accept(header : StringView) -> HeaderAudit

#
audit_accept_charset

source
fn audit_accept_charset(header : StringView) -> HeaderAudit

#
audit_accept_encoding

source
fn audit_accept_encoding(header : StringView) -> HeaderAudit

#
audit_accept_language

source
fn audit_accept_language(header : StringView) -> HeaderAudit

#
audit_api_scenario

source
fn audit_api_scenario() -> HeaderAudit

#
audit_browser_scenario

source
fn audit_browser_scenario() -> HeaderAudit

#
audit_cache_control_header

source
fn audit_cache_control_header(header : StringView) -> HeaderAudit

#
audit_preferences

source
fn audit_preferences(preferences : RequestPreferences) -> HeaderAudit

#
audit_vary_header

source
fn audit_vary_header(header : StringView) -> HeaderAudit

#
browser_preferences_html_en_br

source
fn browser_preferences_html_en_br() -> RequestPreferences

#
browser_response_summary

source
fn browser_response_summary() -> Result[ResponseSummary, ParseError]

#
build_response_variants

source
fn build_response_variants(media_offers : Array[String], language_offers : Array[String], encoding_offers : Array[String], charset_offers : Array[String]) -> Array[ServerVariant]

#
cache_control_has

source
fn cache_control_has(directives : Array[CacheDirective], name : StringView) -> Bool

#
cache_control_value

source
fn cache_control_value(directives : Array[CacheDirective], name : StringView) -> String?

#
cache_is_storable

source
fn cache_is_storable(summary : CachePolicySummary) -> Bool

#
cache_private_fresh_lifetime

source
fn cache_private_fresh_lifetime(summary : CachePolicySummary) -> Int?

#
cache_requires_revalidation

source
fn cache_requires_revalidation(summary : CachePolicySummary) -> Bool

#
cache_shared_fresh_lifetime

source
fn cache_shared_fresh_lifetime(summary : CachePolicySummary) -> Int?

#
canonical_charset

source
fn canonical_charset(input : StringView) -> String

#
charset_candidate_line

source
fn charset_candidate_line(candidate : CharsetCandidate) -> String

#
charset_is_acceptable

source
fn charset_is_acceptable(accept_charset : StringView, charset : StringView) -> Result[Bool, ParseError]

#
conservative_preferences

source
fn conservative_preferences() -> RequestPreferences

#
decision_vary_header

source
fn decision_vary_header(decision : VariantDecision) -> String

#
document_variants

source
fn document_variants() -> Array[ServerVariant]

#
encoding_candidate_line

source
fn encoding_candidate_line(candidate : EncodingCandidate) -> String

#
encoding_is_acceptable

source
fn encoding_is_acceptable(accept_encoding : StringView, coding : StringView) -> Result[Bool, ParseError]

#
etag_list_matches

source
fn etag_list_matches(header_value : StringView, current : EntityTag, strong? : Bool) -> Result[Bool, ParseError]

#
evaluate_if_match

source
fn evaluate_if_match(header_value : StringView, current : EntityTag) -> Result[ConditionalDecision, ParseError]

#
evaluate_if_none_match

source
fn evaluate_if_none_match(http_method : StringView, header_value : StringView, current : EntityTag) -> Result[ConditionalDecision, ParseError]

#
explain_charset_candidates

source
fn explain_charset_candidates(accept_charset : StringView, offers : Array[String]) -> Result[Array[String], ParseError]

#
explain_encoding_candidates

source
fn explain_encoding_candidates(accept_encoding : StringView, offers : Array[String]) -> Result[Array[String], ParseError]

#
explain_language_candidates

source
fn explain_language_candidates(accept_language : StringView, offers : Array[String]) -> Result[Array[String], ParseError]

#
explain_media_candidates

source
fn explain_media_candidates(accept_header : StringView, offers : Array[String]) -> Result[Array[String], ParseError]

#
explain_variant_candidates

source
fn explain_variant_candidates(decision : VariantDecision) -> Array[String]

#
format_audit

source
fn format_audit(audit : HeaderAudit) -> String

#
format_cache_control

source
fn format_cache_control(directives : Array[CacheDirective]) -> String

#
format_cache_summary

source
fn format_cache_summary(summary : CachePolicySummary) -> String

#
format_charset_decision

source
fn format_charset_decision(decision : CharsetDecision) -> String

#
format_conditional_decision

source
fn format_conditional_decision(decision : ConditionalDecision) -> String

#
format_encoding_decision

source
fn format_encoding_decision(decision : EncodingDecision) -> String

#
format_etag

source
fn format_etag(tag : EntityTag) -> String

#
format_language_decision

source
fn format_language_decision(decision : LanguageDecision) -> String

#
format_lines

source
fn format_lines(lines : Array[String]) -> String

#
format_media_decision

source
fn format_media_decision(decision : MediaDecision) -> String

#
format_response_headers

source
fn format_response_headers(headers : Array[Param]) -> String

#
format_response_summary

source
fn format_response_summary(summary : ResponseSummary) -> String

#
format_variant_decision

source
fn format_variant_decision(decision : VariantDecision) -> String

#
join_header_names

source
fn join_header_names(names : Array[String]) -> String

#
language_candidate_line

source
fn language_candidate_line(candidate : LanguageCandidate) -> String

#
media_candidate_line

source
fn media_candidate_line(candidate : MediaCandidate) -> String

#
merge_vary

source
fn merge_vary(left : Array[String], right : Array[String]) -> Result[Array[String], ParseError]

#
negotiate_api_scenario

source
fn negotiate_api_scenario() -> Result[VariantDecision, ParseError]

#
negotiate_browser_document_scenario

source
fn negotiate_browser_document_scenario() -> Result[VariantDecision, ParseError]

#
negotiate_charset

source
fn negotiate_charset(accept_charset : StringView, offers : Array[String]) -> Result[CharsetDecision, ParseError]

#
negotiate_conservative_api_scenario

source
fn negotiate_conservative_api_scenario() -> Result[VariantDecision, ParseError]

#
negotiate_encoding

source
fn negotiate_encoding(accept_encoding : StringView, offers : Array[String]) -> Result[EncodingDecision, ParseError]

#
negotiate_language

source
fn negotiate_language(accept_language : StringView, offers : Array[String]) -> Result[LanguageDecision, ParseError]

#
negotiate_media

source
fn negotiate_media(accept_header : StringView, offers : Array[String]) -> Result[MediaDecision, ParseError]

#
negotiate_response

source
fn negotiate_response(preferences : RequestPreferences, media_offers : Array[String], language_offers : Array[String], encoding_offers : Array[String], charset_offers : Array[String]) -> Result[ResponseNegotiation, ParseError]

#
negotiate_response_summary

source
fn negotiate_response_summary(preferences : RequestPreferences, media_offers : Array[String], language_offers : Array[String], encoding_offers : Array[String], charset_offers : Array[String]) -> Result[ResponseSummary, ParseError]

#
negotiate_variant

source
fn negotiate_variant(preferences : RequestPreferences, variants : Array[ServerVariant]) -> Result[VariantDecision, ParseError]

#
negotiation_matrix_report

source
fn negotiation_matrix_report(preferences : RequestPreferences, variants : Array[ServerVariant]) -> Result[String, ParseError]

#
normalize_header_name

source
fn normalize_header_name(name : StringView) -> Result[String, ParseError]

#
parse_accept

source
fn parse_accept(header : StringView) -> Result[Array[MediaRange], ParseError]

#
parse_accept_charset

source
fn parse_accept_charset(header : StringView) -> Result[Array[CharsetRange], ParseError]

#
parse_accept_encoding

source
fn parse_accept_encoding(header : StringView) -> Result[Array[EncodingRange], ParseError]

#
parse_accept_language

source
fn parse_accept_language(header : StringView) -> Result[Array[LanguageRange], ParseError]

#
parse_cache_control

source
fn parse_cache_control(header : StringView) -> Result[Array[CacheDirective], ParseError]

#
parse_cache_policy

source
fn parse_cache_policy(header : StringView) -> Result[CachePolicySummary, ParseError]

#
parse_charset

source
fn parse_charset(value : StringView) -> Result[CharsetOffer, ParseError]

#
parse_content_encoding

source
fn parse_content_encoding(value : StringView) -> Result[EncodingOffer, ParseError]

#
parse_content_type

source
fn parse_content_type(value : StringView) -> Result[MediaOffer, ParseError]

#
parse_etag

source
fn parse_etag(value : StringView) -> Result[EntityTag, ParseError]

#
parse_etag_list

source
fn parse_etag_list(value : StringView) -> Result[Array[EntityTag], ParseError]

#
parse_header_list

source
fn parse_header_list(value : StringView) -> Result[Array[String], ParseError]

#
parse_language_tag

source
fn parse_language_tag(tag : StringView) -> Result[LanguageOffer, ParseError]

#
parse_vary

source
fn parse_vary(value : StringView) -> Result[Array[String], ParseError]

#
quality_to_string

source
fn quality_to_string(q : Int) -> String

#
response_header_block

source
fn response_header_block(summary : ResponseSummary) -> String

#
response_header_value

source
fn response_header_value(summary : ResponseSummary, name : StringView) -> String?

#
response_headers

source
fn response_headers(summary : ResponseSummary) -> Array[Param]

#
scenario_report

source
fn scenario_report() -> String

#
strong_etag_match

source
fn strong_etag_match(left : EntityTag, right : EntityTag) -> Bool

#
summarize_cache_control

source
fn summarize_cache_control(directives : Array[CacheDirective]) -> Result[CachePolicySummary, ParseError]

#
summarize_response

source
fn summarize_response(decision : VariantDecision) -> ResponseSummary

#
variant_candidate_line

source
fn variant_candidate_line(candidate : VariantCandidate) -> String

#
vary_contains

source
fn vary_contains(vary : Array[String], field : StringView) -> Bool

#
weak_etag_match

source
fn weak_etag_match(left : EntityTag, right : EntityTag) -> Bool

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io