From 19443917b2d6edc1bf64f46663a38e7ffe540c68 Mon Sep 17 00:00:00 2001 From: Dacec Date: Fri, 30 Aug 2024 17:19:14 +0800 Subject: [PATCH 1/2] =?UTF-8?q?update:=20=E6=9B=B4=E6=96=B0=E8=84=9A?= =?UTF-8?q?=E6=9C=AC=EF=BC=8C=E6=9B=B4=E6=96=B0cjd=E3=80=82=E6=89=8B?= =?UTF-8?q?=E5=8A=A8=E4=BF=AE=E5=A4=8D=E4=B8=80=E9=83=A8=E5=88=86=E9=94=99?= =?UTF-8?q?=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cangjie_libs/compress/zlib.cjd | 152 +- cangjie_libs/crypto/crypto.cjd | 337 ++ cangjie_libs/crypto/digest.cjd | 316 ++ cangjie_libs/crypto/keys.cjd | 487 +- cangjie_libs/crypto/x509.cjd | 920 +++- cangjie_libs/encoding/base64.cjd | 12 + cangjie_libs/encoding/hex.cjd | 12 + cangjie_libs/encoding/json.cjd | 417 +- cangjie_libs/encoding/json.stream.cjd | 574 ++- cangjie_libs/encoding/url.cjd | 233 + cangjie_libs/encoding/xml.cjd | 134 + cangjie_libs/fuzz/fuzz.cjd | 455 ++ cangjie_libs/log/log.cjd | 464 +- cangjie_libs/logger/logger.cjd | 345 ++ cangjie_libs/net/http.cjd | 1817 +++++++- cangjie_libs/net/tls.cjd | 565 ++- cangjie_libs/serialization/serialization.cjd | 368 ++ cangjie_libs/std/argopt.cjd | 52 + cangjie_libs/std/ast.cjd | 4257 +++++++++++++++++- cangjie_libs/std/binary.cjd | 369 +- cangjie_libs/std/collection.cjd | 1341 +++++- cangjie_libs/std/collection.concurrent.cjd | 372 ++ cangjie_libs/std/console.cjd | 221 + cangjie_libs/std/convert.cjd | 210 + cangjie_libs/std/core.cjd | 3127 ++++++++++++- cangjie_libs/std/crypto.cipher.cjd | 18 + cangjie_libs/std/crypto.digest.cjd | 37 + cangjie_libs/std/database.sql.cjd | 1171 ++++- cangjie_libs/std/ffi.python.cjd | 74 + cangjie_libs/std/format.cjd | 118 + cangjie_libs/std/fs.cjd | 677 ++- cangjie_libs/std/io.cjd | 625 ++- cangjie_libs/std/log.cjd | 162 +- cangjie_libs/std/math.cjd | 1948 ++++++++ cangjie_libs/std/math.numeric.cjd | 1176 ++++- cangjie_libs/std/net.cjd | 2253 ++++++++- cangjie_libs/std/objectpool.cjd | 14 + cangjie_libs/std/os.cjd | 50 + cangjie_libs/std/os.posix.cjd | 709 +++ cangjie_libs/std/os.process.cjd | 177 +- cangjie_libs/std/overflow.cjd | 3197 +++++++++++++ cangjie_libs/std/random.cjd | 185 + cangjie_libs/std/reflect.cjd | 1097 ++++- cangjie_libs/std/regex.cjd | 229 + cangjie_libs/std/runtime.cjd | 40 + cangjie_libs/std/sort.cjd | 50 + cangjie_libs/std/sync.cjd | 1526 ++++++- cangjie_libs/std/time.cjd | 931 +++- cangjie_libs/std/unicode.cjd | 130 + cangjie_libs/std/unittest.cjd | 1004 ++++- cangjie_libs/std/unittest.common.cjd | 404 +- cangjie_libs/std/unittest.diff.cjd | 16 + cangjie_libs/std/unittest.mock.cjd | 608 ++- cangjie_libs/std/unittest.prop_test.cjd | 778 +++- index.js | 111 +- 55 files changed, 36640 insertions(+), 432 deletions(-) diff --git a/cangjie_libs/compress/zlib.cjd b/cangjie_libs/compress/zlib.cjd index 5dfe07c..b3386a9 100644 --- a/cangjie_libs/compress/zlib.cjd +++ b/cangjie_libs/compress/zlib.cjd @@ -3,29 +3,138 @@ package compress.zlib // --------------------------- // -----classes // --------------------------- +/** + * 压缩输入流。 + * 可将 CompressInputStream 实例绑定到任意 InputStream 输入流，将该输入流中的数据压缩，并输出到字节数组。 +*/ public class CompressInputStream <: InputStream { + /** + * 构造一个压缩输入流。 + * 需绑定一个输入流，可设置压缩数据格式、压缩等级、内部缓冲区大小（每次从输入流中读取多少数据进行压缩）。 + * @param inputStream: InputStream - 待压缩的输入流。 + * @param wrap!: WrapType - 压缩数据格式，默认值为 DeflateFormat。 + * @param compressLevel!: CompressLevel - 压缩等级，默认值为 DefaultCompression。 + * @param bufLen!: Int64 - 输入流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。 + * @throws ZlibException - 当 bufLen 小于等于 0，输入流分配内存失败，或压缩资源初始化失败，抛出异常。 + */ public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512) + + /** + * 关闭压缩输入流。 + * 当前 CompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0，否则可能导致绑定的 InputStream 并未被全部压缩。 + * @throws ZlibException - 如果释放压缩资源失败，抛出异常。 + */ public func close(): Unit + + /** + * 从绑定的输入流中读取数据并压缩，压缩后数据放入指定的字节数组中。 + * @param outBuf: Array - 用来存放压缩后数据的缓冲区。 + * @return Int64 - 如果压缩成功，返回压缩后字节数，如果绑定的输入流中数据已经全部压缩完成，或者该压缩输入流被关闭，返回 0。 + * @throws ZlibException - 当 outBuf 为空，或压缩数据失败，抛出异常。 + */ public func read(outBuf: Array): Int64 } +/** + * 压缩输出流。 + * 可将 CompressOutputStream 实例绑定到任意 OutputStream 类型输出流，读取、压缩指定字节数组中的数据，并将压缩后数据输出到绑定的输出流。 +*/ public class CompressOutputStream <: OutputStream { + /** + * 构造一个压缩输出流，需绑定一个输出流，可设置压缩数据类型、压缩等级、内部缓冲区大小（每得到多少压缩后数据往输出流写出）。 + * @param outputStream: OutputStream - 绑定的输出流，压缩后数据将写入该输出流。 + * @param wrap!: WrapType - 压缩数据格式，默认值为 DeflateFormat。 + * @param compressLevel!: CompressLevel - 压缩等级，默认值为 DefaultCompression。 + * @param bufLen!: Int64 - 输出流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。 + * @throws ZlibException - 如果 bufLen 小于等于 0，输出流分配内存失败，或压缩资源初始化失败，抛出异常。 + */ public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512) + + /** + * 关闭当前压缩输出流实例。 + * 关闭时，将写入剩余压缩数据（包括缓冲区中数据，以及压缩尾部信息），并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。在调用 close 函数前，绑定的输出流里已写入的数据并不是一段完整的压缩数据，调用 close 函数后，才会把剩余压缩数据写入绑定的输出流，使其完整。 + * @throws ZlibException - 如果当前压缩输出流已经被关闭，或释放压缩资源失败，抛出异常。 + */ public func close(): Unit + + /** + * 刷新压缩输出流。将内部缓冲区里已压缩的数据刷出并写入绑定的输出流，然后刷新绑定的输出流。 + * @throws ZlibException - 如果当前压缩输出流已经被关闭，抛出异常。 + */ public func flush(): Unit + + /** + * 将指定字节数组中的数据进行压缩，并写入输出流，当数据全部压缩完成并写入输出流，函数返回。 + * @param inBuf: Array - 待压缩的字节数组。 + * @throws ZlibException - 如果当前压缩输出流已经被关闭，或压缩数据失败，抛出异常。 + */ public func write(inBuf: Array): Unit } +/** + * 解压输入流。 + * 可将 DecompressInputStream 实例绑定到任意 InputStream 输入流，读取、解压其中的数据，并将解压后数据输出到指定字节数组。 +*/ public class DecompressInputStream <: InputStream { + /** + * 构造一个解压输入流。 + * 需绑定一个输入流，可设置待解压数据格式、内部缓冲区大小（每次从输入流中读取多少数据进行解压）。 + * @param inputStream: InputStream - 待压缩的输入流。 + * @param wrap!: WrapType - 待解压数据格式，默认值为 DeflateFormat。 + * @param bufLen!: Int64 - 输入流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。 + * @throws ZlibException - 如果 bufLen 小于等于 0，输入流分配内存失败，或待解压资源初始化失败，抛出异常。 + */ public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512) + + /** + * 关闭解压输入流。 + * 当前 DecompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0，否则可能导致绑定的 InputStream 并未被全部解压。 + * @throws ZlibException - 如果释放解压资源失败，抛出异常。 + */ public func close(): Unit + + /** + * 从绑定的输入流中读取数据并解压，解压后数据放入指定的字节数组中。 + * @param outBuf: Array - 用来存放解压后数据的缓冲区。 + * @return Int64 - 如果解压成功，返回解压后字节数，如果绑定的输入流中数据已经全部解压完成，或者该解压输入流被关闭，返回 0。 + * @throws ZlibException - 当 outBuf 为空，或解压数据失败，抛出异常。 + */ public func read(outBuf: Array): Int64 } +/** + * 解压输出流。 + * 可将 DecompressOutputStream 实例绑定到指定的 OutputStream 类型输出流，读取、解压指定字节数组中的数据，并将解压后数据输出到绑定的输出流。 +*/ public class DecompressOutputStream <: OutputStream { + /** + * 构造一个解压输出流。 + * 需绑定一个输出流，可设置压缩数据类型、压缩等级、内部缓冲区大小（解压后数据会存入内部缓冲区，缓冲区存满后再写到输出流）。 + * @param outputStream: OutputStream - 绑定的输出流，解压后数据将写入该输出流。 + * @param wrap!: WrapType - 待解压数据格式，默认值为 DeflateFormat。 + * @param bufLen!: Int64 - 输出流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。 + * @throws ZlibException - 如果 bufLen 小于等于 0，输出流分配内存失败，或解压资源初始化失败，抛出异常。 + */ public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512) + + /** + * 关闭当前解压输出流实例。 + * 关闭时，将写入剩余解压后数据，并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。如果之前 write 函数已处理的压缩数据不完整，调用 close 函数时会因为解压数据不全而抛出异常。 + * @throws ZlibException - 如果当前压缩输出流已经被关闭，通过 write 函数传入的待解压数据不完整，或释放压缩资源失败，抛出异常。 + */ public func close(): Unit + + /** + * 刷新解压输出流。将内部缓冲区里已解压的数据写入绑定的输出流，然后刷新绑定的输出流。 + * @throws ZlibException - 如果当前解压输出流已经被关闭，抛出异常。 + */ public func flush(): Unit + + /** + * 将指定字节数组中的数据进行解压，并写入输出流，当数据全部解压完成并写入输出流，函数返回。 + * @param inBuf: Array - 待解压的字节数组。 + * @throws ZlibException - 如果当前解压输出流已经被关闭，或解压数据失败，抛出异常。 + */ public func write(inBuf: Array): Unit } @@ -33,22 +142,55 @@ public class DecompressOutputStream <: OutputStream { // --------------------------- // -----enums // --------------------------- +/** + * 压缩等级。 + * 压缩等级决定了压缩率和压缩速度，目前支持三种压缩等级，压缩率由小到大，压缩速度由快到慢依次为：BestSpeed、DefaultCompression、BestCompression。 +*/ public enum CompressLevel { - BestCompression - BestSpeed - DefaultCompression + /** + * 构造一个压缩率优先的压缩等级枚举实例，表示压缩率最高，压缩速度相对降低。 + */ + | BestCompression + + /** + * 构造一个压缩速度优先的压缩等级枚举实例，表示压缩速度最快，压缩率相对较低。 + */ + | BestSpeed + + /** + * 构造一个压缩等级枚举实例，表示默认压缩等级。 + */ + | DefaultCompression } +/** + * 压缩数据格式。 + * 目前支持 DeflateFormat 和 GzipFormat 两种格式。 +*/ public enum WrapType { - DeflateFormat - GzipFormat + /** + * 构造一个表示 Deflate 压缩数据格式的枚举实例。 + */ + | DeflateFormat + + /** + * 构造一个表示 Gzip 压缩数据格式的枚举实例。 + */ + | GzipFormat } // --------------------------- // -----exceptions // --------------------------- +/** + * zlib 包的异常类。 +*/ public class ZlibException <: Exception { + /** + * 根据异常信息创建 ZlibException 实例。 + * @param message: String - 异常提示信息。 + */ public init(message: String) } diff --git a/cangjie_libs/crypto/crypto.cjd b/cangjie_libs/crypto/crypto.cjd index f40e7f5..008dd39 100644 --- a/cangjie_libs/crypto/crypto.cjd +++ b/cangjie_libs/crypto/crypto.cjd @@ -3,48 +3,301 @@ package crypto.crypto // --------------------------- // -----classes // --------------------------- +/** + * 用于生成加密安全的伪随机数。 + * 和 Random 相比，主要有三个方面不同： +*/ public class SecureRandom { + /** + * 创建 SecureRandom 实例，可指定是否使用更加安全的加密安全伪随机生成器，加密安全伪随机生成器可用于会话密钥和证书私钥等加密场景。 + * @param priv!: Bool - 设置为 true 表示使用加密安全伪随机生成器。 + */ public init(priv!: Bool = false) + + /** + * 获取一个随机的 Bool 类型实例。 + * @return Bool - 一个随机的 Bool 类型实例。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextBool(): Bool + + /** + * 获取一个指定长度的随机字节的数组。 + * @param length: Int32 - 要生成的随机字节数组的长度。 + * @return Array - 一个随机字节数组。 + * @throws IllegalArgumentException - 当参数 length 小于等于 0，抛出异常。 + */ public func nextBytes(length: Int32): Array + + /** + * 获取一个 Float16 类型且在区间 [0.0, 1.0) 内的随机数。 + * @return Float16 - 一个 Float16 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextFloat16(): Float16 + + /** + * 获取一个 Float32 类型且在区间 [0.0, 1.0) 内的随机数。 + * @return Float32 - 一个 Float32 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextFloat32(): Float32 + + /** + * 获取一个 Float64 类型且在区间 [0.0, 1.0) 内的随机数。 + * @return Float64 - 一个 Float64 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextFloat64(): Float64 + + /** + * 默认获取一个 Float16 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。 + * @param mean!: Float16 - 均值。 + * @param sigma!: Float16 - 标准差。 + * @return Float16 - 一个 Float16 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextGaussianFloat16(mean!: Float16 = 0.0, sigma!: Float16 = 1.0): Float16 + + /** + * 默认获取一个 Float32 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。 + * @param mean!: Float32 - 均值。 + * @param sigma!: Float32 - 标准差。 + * @return Float32 - 一个 Float32 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextGaussianFloat32(mean!: Float32 = 0.0, sigma!: Float32 = 1.0): Float32 + + /** + * 默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。 + * @param mean!: Float64 - 均值。 + * @param sigma!: Float64 - 标准差。 + * @return Float64 - 一个 Float64 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64 + + /** + * 获取一个 Int16 类型的随机数。 + * @return Int16 - 一个 Int16 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextInt16(): Int16 + + /** + * 获取一个 Int32 类型的随机数。 + * @return Int32 - 一个 Int32 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextInt32(): Int32 + + /** + * 获取一个 Int16 类型且在区间 [0, max) 内的随机数。 + * @param max: Int16 - 区间最大值。 + * @return Int16 - 一个 Int16 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为非正数时，抛出异常。 + */ public func nextInt16(max: Int16): Int16 + + /** + * 获取一个 Int32 类型且在区间 [0, max) 内的随机数。 + * @param max: Int32 - 区间最大值。 + * @return Int32 - 一个 Int32 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为非正数时，抛出异常。 + */ public func nextInt32(max: Int32): Int32 + + /** + * 获取一个 Int64 类型的随机数。 + * @return Int64 - 一个 Int64 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextInt64(): Int64 + + /** + * 获取一个 Int64 类型且在区间 [0, max) 内的随机数。 + * @param max: Int64 - 区间最大值。 + * @return Int64 - 一个 Int64 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为非正数时，抛出异常。 + */ public func nextInt64(max: Int64): Int64 + + /** + * 获取一个 Int8 类型的随机数。 + * @return Int8 - 一个 Int8 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextInt8(): Int8 + + /** + * 获取一个 Int8 类型且在区间 [0, max) 内的随机数。 + * @param max: Int8 - 区间最大值。 + * @return Int8 - 一个 Int8 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为非正数时，抛出异常。 + */ public func nextInt8(max: Int8): Int8 + + /** + * 获取一个 UInt16 类型的随机数。 + * @return UInt16 - 一个 UInt16 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextUInt16(): UInt16 + + /** + * 获取一个 UInt16 类型且在区间 [0, max) 内的随机数。 + * @param max: UInt16 - 区间最大值。 + * @return UInt16 - 一个 UInt16 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为 0 时，抛出异常。 + */ public func nextUInt16(max: UInt16): UInt16 + + /** + * 获取一个 UInt32 类型的随机数。 + * @return UInt32 - 一个 UInt32 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextUInt32(): UInt32 + + /** + * 获取一个 UInt32 类型且在区间 [0, max) 内的随机数。 + * @param max: UInt32 - 区间最大值。 + * @return UInt32 - 一个 UInt32 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为 0 时，抛出异常。 + */ public func nextUInt32(max: UInt32): UInt32 + + /** + * 获取一个 UInt64 类型的随机数。 + * @return UInt64 - 一个 UInt64 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextUInt64(): UInt64 + + /** + * 获取一个 UInt64 类型且在区间 [0, max) 内的随机数。 + * @param max: UInt64 - 区间最大值。 + * @return UInt64 - 一个 UInt64 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为 0 时，抛出异常。 + */ public func nextUInt64(max: UInt64): UInt64 + + /** + * 获取一个 UInt8 类型的随机数。 + * @return UInt8 - 一个 UInt8 类型的随机数。 + * @throws SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。 + */ public func nextUInt8(): UInt8 + + /** + * 获取一个 UInt8 类型且在区间 [0, max) 内的随机数。 + * @param max: UInt8 - 区间最大值。 + * @return UInt8 - 一个 UInt8 类型的随机数。 + * @throws IllegalArgumentException - 当 max 为 0 时，抛出异常。 + */ public func nextUInt8(max: UInt8): UInt8 } +/** + * 提供国密SM4对称加解密。 + * 目前 SM4 支持 的加解密工作模式由 OperationMode 定义，目前支持 ECB、CBC、OFB、CFB、CTR、GCM模式。 + * 不同的工作模式可能对应的加解密实现不同，安全性也不同。需要选择和场景适配的加解密工作模式。 + * iv 初始化向量在 GCM 模式下可以设置推荐长度是12字节，在 CBC、OFB、CFB、CTR 模式下 iv 长度是16字节，在 ECB 模式下 iv 可以不设置。 + * paddingMode 填充模式模式由 PaddingMode 定义， 目前支持 NoPadding 非填充、PKCS7Padding PKCS7填充。默认是 PKCS7 填充。 + * paddingMode 设置对ECB 和 CBC 有效，ECB 和 CBC 分组加解密需要分组长度等于 blockSize。会根据填充模式进行填充。 paddingMode 设置对 OFB、CFB、CTR、GCM 工作模式无效，这些工作模式均无需填充。 + * 如果选择 NoPadding 模式，即不填充。则在 ECB 和 CBC 工作模式下用户需要对数据是否可以分组负责，如果数据不能分组，或者最后一组数据长度不足 blockSize 则会报错。 + * aad 附加数据，仅在 GCM 模式下使用，由用户填充，参与摘要计算，默认为空。 + * tagSize 设置摘要长度，仅在 GCM 模式下使用，默认值为 SM4_GCM_TAG_SIZE 16字节，最小不能低于12字节，最大不能超过16字节。 + * 如果是 GCM 工作模式。加密结果的后 tagSize 位是摘要数据。 +*/ public class SM4 <: BlockCipher { + /** + * 创建 SM4 实例，可指定在不同工作模式下参数。 + * @param optMode: OperationMode - 设置加解密工作模式。 + * @param key: Array - 密钥，长度为16字节。 + * @param iv!: Array - 初始化向量。 + * @param paddingMode!: PaddingMode - 设置填充模式。 + * @param aad!: Array - 设置附加数据。 + * @param tagSize: Int64 - 设置摘要长度。 + * @throws CryptoException - 参数设置不正确，实例化失败。 + */ public init( optMode: OperationMode, key: Array, iv!: Array = Array(), paddingMode!: PaddingMode = PaddingMode.PKCS7Padding, aad!: Array = Array(), tagSize!: Int64 = SM4_GCM_TAG_SIZE ) + + /** + * 附加数据。 + */ public prop aad: Array + + /** + * 分组长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * 密钥长度。 + */ public prop keySize: Int64 + + /** + * 密钥。 + */ public prop key: Array + + /** + * 工作模式。 + */ public prop optMode: OperationMode + + /** + * 填充模式。 + */ public prop paddingMode: PaddingMode + + /** + * 初始化向量。 + */ public prop iv: Array + + /** + * 初始化向量长度。 + */ public prop ivSize: Int64 + + /** + * 摘要长度。 + */ public prop tagSize: Int64 + + /** + * 加密一段数据数据。 + * @param input: Array - 输入字节序列。 + * @return Array - 加密后的结果。 + * @throws CryptoException - 加密失败，抛出异常。 + */ public func encrypt(input: Array): Array + + /** + * 对输入流进行加密，一般如果数据过大无法一次对其加密，可以对数据流进行加密。 + * @param input: InputStream - 待加密的输入数据流。 + * @param output: OutputStream - 解密后的输出数据流。 + * @throws CryptoException - 加密失败，抛出异常。 + */ public func encrypt(input: InputStream, output: OutputStream) + + /** + * 解密一段数据数据。 + * @param input: Array - 输入字节序列。 + * @return Array - 解密后的结果。 + * @throws CryptoException - 解密失败，抛出异常。 + */ public func decrypt(input: Array): Array + + /** + * 对输入流进行解密，一般如果数据过大无法一次对其解密，可以对数据流进行解密。 + * @param input: InputStream - 待解密的输入数据流。 + * @param output: OutputStream - 解密后的输出数据流。 + * @throws CryptoException - 解密失败，抛出异常。 + */ public func decrypt(input: InputStream, output: OutputStream) } @@ -52,8 +305,19 @@ public class SM4 <: BlockCipher { // --------------------------- // -----exceptions // --------------------------- +/** + * crypto 包安全随机数的异常类。 +*/ public class SecureRandomException <: Exception { + /** + * 创建默认的 SecureRandomException 实例，异常提示消息为空。 + */ public init() + + /** + * 根据异常信息创建 SecureRandomException 实例。 + * @param message: String - 异常提示信息。 + */ public init(message: String) } @@ -61,24 +325,97 @@ public class SecureRandomException <: Exception { // --------------------------- // -----structs // --------------------------- +/** + * 对称加解密算法的工作模式。 +*/ public struct OperationMode <: ToString & Equatable { + /** + * Electronic CodeBook(单子密码本)工作模式。 + */ public static let ECB + + /** + * Cipher Block Chaining(密码分组链接)工作模式。 + */ public static let CBC + + /** + * Output FeedBack(输出反馈)工作模式。 + */ public static let OFB + + /** + * Output FeedBack(密文反馈)工作模式。 + */ public static let CFB + + /** + * CounTeR(计数器)工作模式。 + */ public static let CTR + + /** + * Galois Counter(伽罗瓦计数器)工作模式。 + */ public static let GCM + + /** + * operation 分组加解密的工作模式，目前支持 ECB、CBC CFB OFB CTR GCM。 + */ public let mode: String + + /** + * 获取工作模式字符串。 + * @return String - 工作模式字符串。 + */ public override func toString(): String + + /** + * 工作模式比较是否相同。 + * @param other: OperationMode - 工作模式。 + * @return Bool - true 相同， false不相同。 + */ public operator override func ==(other: OperationMode): Bool + + /** + * 工作模式比较是否不相同。 + * @param other: OperationMode - 工作模式。 + * @return Bool - true 不相同， false相同。 + */ public operator override func !=(other: OperationMode): Bool } +/** + * 对称加解密算法的工填充模式。 +*/ public struct PaddingMode <: Equatable { + /** + * 不填充。 + */ public static let NoPadding + + /** + * 采用PKCS7协议填充。 + */ public static let PKCS7Padding + + /** + * 分组加解密填充方式，目前支持非填充和 pkcs7 填充。 + */ public let paddingType: Int64 + + /** + * 填充模式比较是否相同。 + * @param other: PaddingMode - 填充模式。 + * @return Bool - true 相同， false不相同。 + */ public operator override func ==(other: PaddingMode): Bool + + /** + * 工作模式比较是否不相同。 + * @param other: PaddingMode - 填充模式。 + * @return Bool - true 不相同， false相同。 + */ public operator override func !=(other: PaddingMode): Bool } diff --git a/cangjie_libs/crypto/digest.cjd b/cangjie_libs/crypto/digest.cjd index 438cce4..c21bf59 100644 --- a/cangjie_libs/crypto/digest.cjd +++ b/cangjie_libs/crypto/digest.cjd @@ -3,77 +3,335 @@ package crypto.digest // --------------------------- // -----classes // --------------------------- +/** + * 提供 HMAC 算法的实现。目前支持的摘要算法包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、SM3。 +*/ public class HMAC <: Digest { + /** + * HMAC 所选 Hash 算法信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * HMAC 所选 Hash 算法的摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 构造函数，创建 HMAC 对象。 + * @param key: Array - 密钥，建议该参数不小于所选Hash算法摘要的长度。 + * @param digest: () -> Digest- hash 算法。 + * @throws CryptoException - key 值为空时，抛出异常。 + */ public init(key: Array, digest: () -> Digest) + + /** + * 构造函数，创建 HMAC 对象。 + * @param key: Array - 密钥，建议该参数不小于所选Hash算法摘要的长度。 + * @param algorithm: HashType - hash 算法。 + * @throws CryptoException - key 值为空时，抛出异常。 + */ public init(key: Array, algorithm: HashType) + + /** + * 比较两个信息摘要是否相等，且不泄露比较时间，即比较不采用传统短路原则，从而防止 timing attack 类型的攻击。 + * @param mac1: Array - 需要比较的信息摘要序列。 + * @param mac2: Array - 需要比较的信息摘要序列。 + * @return Bool - 信息摘要是否相同, true 相同, false 不相同。 + */ public static func equal(mac1: Array, mac2: Array): Bool + + /** + * 返回生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的信息摘要字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 HMAC 对象到初始状态，清理 HMAC 上下文。 + * @throws CryptoException - 当内部错误，重置失败，抛此异常。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 HMAC 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 需要追加的字节序列。 + * @throws CryptoException - 当 buffer 为空、finish 已经调用生成信息摘要场景，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 MD5 算法的实现接口。 +*/ public class MD5 <: Digest { + /** + * MD5 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * MD5 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 MD5 对象。 + */ public init() + + /** + * 返回生成的 MD5 值，注意调用 finish 后 MD5 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 MD5 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 MD5 对象到初始状态，清理 MD5 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 MD5 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SHA1 算法的实现接口。 +*/ public class SHA1 <: Digest { + /** + * SHA1 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SHA1 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SHA1 对象。 + */ public init() + + /** + * 返回生成的 SHA1 值，注意调用 finish 后 SHA1 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SHA1 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SHA1 对象到初始状态，清理 SHA1 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SHA1 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SHA224 算法的实现接口。 +*/ public class SHA224 <: Digest { + /** + * SHA224 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SHA224 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SHA224 对象。 + */ public init() + + /** + * 返回生成的 SHA224 值，注意调用 finish 后 SHA224 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SHA224 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SHA224 对象到初始状态，清理 SHA224 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SHA224 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SHA256 算法的实现接口。 +*/ public class SHA256 <: Digest { + /** + * SHA256 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SHA256 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SHA256 对象。 + */ public init() + + /** + * 返回生成的 SHA256 值，注意调用 finish 后 SHA256 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SHA256 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SHA256 对象到初始状态，清理 SHA256 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SHA256 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SHA384 算法的实现接口。 +*/ public class SHA384 <: Digest { + /** + * SHA384 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SHA384 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SHA384 对象。 + */ public init() + + /** + * 返回生成的 SHA384 值，注意调用 finish 后 SHA384 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SHA384 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SHA384 对象到初始状态，清理 SHA384 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SHA384 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SHA512 算法的实现接口。 +*/ public class SHA512 <: Digest { + /** + * SHA512 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SHA512 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SHA512 对象。 + */ public init() + + /** + * 返回生成的 SHA512 值，注意调用 finish 后 SHA512 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SHA512 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SHA512 对象到初始状态，清理 SHA512 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SHA512 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } +/** + * 提供 SM3 算法的实现接口。 +*/ public class SM3 <: Digest { + /** + * SM3 信息块长度，单位字节。 + */ public prop blockSize: Int64 + + /** + * SM3 摘要信息长度，单位字节。 + */ public prop size: Int64 + + /** + * 无参构造函数，创建 SM3 对象。 + */ public init() + + /** + * 返回生成的 SM3 值，注意调用 finish 后 SM3 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。 + * @return Array - 生成的 SM3 字节序列。 + * @throws CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。 + */ public func finish(): Array + + /** + * 重置 SM3 对象到初始状态，清理 SM3 上下文。 + */ public func reset(): Unit + + /** + * 使用给定的 buffer 更新 SM3 对象，在调用 finish 前可以多次更新。 + * @param buffer: Array - 输入字节序列。 + * @throws CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。 + */ public func write(buffer: Array): Unit } @@ -81,8 +339,19 @@ public class SM3 <: Digest { // --------------------------- // -----exceptions // --------------------------- +/** + * 此类为摘要和加解密出现错误时抛出的异常。 +*/ public class CryptoException <: Exception { + /** + * 无参构造函数，构造CryptoException异常。 + */ public init() + + /** + * 根据异常信息构造 CryptoException 异常类对象。 + * @param message: String - 异常信息。 + */ public init(message: String) } @@ -90,16 +359,63 @@ public class CryptoException <: Exception { // --------------------------- // -----structs // --------------------------- +/** + * 此类为 Hash 算法类别结构体，MD5、SHA1、SHA224、SHA256、SHA384、SHA512均为常用摘要算法。 +*/ public struct HashType <: ToString & Equatable { + /** + * 返回 MD5 类型。 + */ public static prop MD5: HashType + + /** + * 返回 SHA1 类型。 + */ public static prop SHA1: HashType + + /** + * 返回 SHA224 类型。 + */ public static prop SHA224: HashType + + /** + * 返回 SHA256 类型。 + */ public static prop SHA256: HashType + + /** + * 返回 SHA384 类型。 + */ public static prop SHA384: HashType + + /** + * 返回 SHA512 类型。 + */ public static prop SHA512: HashType + + /** + * 返回 SM3 类型。 + */ public static prop SM3: HashType + + /** + * 获取 Hash 算法名称。 + * @return String - Hash 算法名称。 + */ public func toString(): String + + /** + * 判断两 HashType 是否引用同一实例。 + * @param other: HashType - 对比的 HashType。 + * @return Bool - 相同返回 true；否则，返回 false。 + */ public operator override func ==(other: HashType): Bool + + /** + * 判断两 HashType 是否引用不同实例。 + * @param other: HashType - 对比的 HashType。 + * @return Bool - 不相同返回 true；否则，返回 false。 + */ public operator override func !=(other: HashType): Bool } diff --git a/cangjie_libs/crypto/keys.cjd b/cangjie_libs/crypto/keys.cjd index 86f69c8..e36ba7f 100644 --- a/cangjie_libs/crypto/keys.cjd +++ b/cangjie_libs/crypto/keys.cjd @@ -3,78 +3,472 @@ package crypto.keys // --------------------------- // -----classes // --------------------------- +/** + * ECDSA 私钥类，提供生成 ECDSA 私钥能力，ECDSA 的私钥支持签名操作，同时支持 PEM 和 DER 格式的编码解码。 +*/ public class ECDSAPrivateKey <: PrivateKey { + /** + * init 初始化生成私钥。 + * @param curve: Curve - 椭圆曲线类型。 + * @throws CryptoException - 初始化失败，抛出异常。 + */ public init(curve: Curve) + + /** + * 将私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @return ECDSAPrivateKey - 解码出的 ECDSA 私钥。 + * @throws CryptoException - 解码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): ECDSAPrivateKey + + /** + * 将加密的私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return ECDSAPrivateKey - 解码出的 ECDSA 私钥。 + * @throws CryptoException - 解码失败、解密失败或者参数密码为空字符串，抛出异常。 + */ public static func decodeDer(blob: DerBlob, password!: ?String): ECDSAPrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @return ECDSAPrivateKey - 解码出的 ECDSA 私钥。 + * @throws CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): ECDSAPrivateKey + + /** + * 将私钥从PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return ECDSAPrivateKey - 解码出的 ECDSA 私钥。 + * @throws CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String, password!: ?String): ECDSAPrivateKey + + /** + * 将私钥编码为 DER 格式。 + * @return DerBlob - 编码后的Der格式私钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToDer(): DerBlob + + /** + * 使用 AES-256-CBC 加密私钥，将私钥编码为 DER 格式。 + * @param password!: ?String - 加密私钥需要提供的密码，密码为 None 时则不加密。 + * @return DerBlob - 编码后的DER格式私钥。 + * @throws CryptoException - 编码失败、加密失败或者参数密码为空字符串，抛出异常。 + */ public func encodeToDer(password!: ?String): DerBlob + + /** + * 将私钥编码为 PEM 格式。 + * @return PemEntry - 私钥PEM 格式的对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToPem(): PemEntry + + /** + * sign 对数据的摘要结果进行签名。 + * @param digest: Array - 数据的摘要结果。 + * @return Array - 签名后的数据。 + * @throws CryptoException - 签名失败，抛出异常。 + */ public func sign(digest: Array): Array + + /** + * 输出私钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String } +/** + * ECDSA 公钥类，提供生成 ECDSA 公钥能力，ECDSA 公钥支持验证签名操作，支持 PEM 和 DER 格式的编码解码。 +*/ public class ECDSAPublicKey <: PublicKey { + /** + * init 初始化公钥，从私钥中获取对应的公钥。 + * @param pri: ECDSAPrivateKey - ECDSA 私钥。 + * @throws CryptoException - 初始化失败，抛出异常。 + */ public init(pri: ECDSAPrivateKey) + + /** + * 将公钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的公钥对象。 + * @return ECDSAPublicKey - 解码出的 ECDSA 公钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): ECDSAPublicKey + + /** + * 将公钥从 PEM 格式解码。 + * @param text: String - PEM 格式的公钥字符流。 + * @return ECDSAPublicKey - 解码出的 ECDSA 公钥。 + * @throws CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): ECDSAPublicKey + + /** + * 将公钥编码为 DER 格式。 + * @return DerBlob - 编码后的Der格式公钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToDer(): DerBlob + + /** + * 将公钥编码为 PEM 格式。 + * @return PemEntry - PemEntry 对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToPem(): PemEntry + + /** + * 输出公钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String + + /** + * verify 验证签名结果。 + * @param digest: Array - 数据的摘要结果。 + * @param sig: Array - 数据的签名结果。 + * @return Bool - 返回 true 表示验证成功，false 失败。 + */ public func verify(digest: Array, sig: Array): Bool } +/** + * RSA 私钥类，提供生成 RSA 私钥能力，RSA 私钥支持签名和解密操作，支持 PEM 和 DER 格式的编码解码，符合 PKCS1 标准。 +*/ public class RSAPrivateKey <: PrivateKey { + /** + * init 初始化生成私钥, 公钥指数默认值为 65537，业界推荐。公钥指数e的大小直接影响了RSA算法的安全性和加密效率。通常情况下，e的值越小，加密速度越快，但安全性越低。 + * @param bits: Int32 - 密钥长度，需要大于等于 512 位，并且小于等于 16384 位。 + * @throws CryptoException - 密钥长度不符合要求或初始化失败，抛出异常。 + */ public init(bits: Int32) + + /** + * init 初始化生成私钥，允许用户指定公共指数。 + * @param bits: Int32 - 密钥长度，需要大于等于 512 位，并且小于等于 16384 位，推荐使用的密钥长度不小于 3072 位。 + * @param e: BigInt - 公钥公共指数，范围是 [3, 2^256-1] 的奇数。 + * @throws CryptoException - 密钥长度不符合要求、公钥公共指数值不符合要求或初始化失败，抛出异常。 + */ public init(bits: Int32, e: BigInt) + + /** + * 将私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @return RSAPrivateKey - 解码出的 RSA 私钥。 + * @throws CryptoException - 解码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): RSAPrivateKey + + /** + * 将加密的私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return RSAPrivateKey - 解码出的 RSA 私钥。 + * @throws CryptoException - 解码失败、解密失败或者参数密码为空字符串，抛出异常。 + */ public static func decodeDer(blob: DerBlob, password!: ?String): RSAPrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @return RSAPrivateKey - 解码出的 RSA 私钥。 + * @throws CryptoException - 解码失败、解密失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): RSAPrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return RSAPrivateKey - 解码出的 RSA 私钥。 + * @throws CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String, password!: ?String): RSAPrivateKey + + /** + * decrypt 解密出原始数据。 + * @param input: InputStream - 加密的数据。 + * @param output: OutputStream - 解密后的数据。 + * @param padType!: PadOption - 填充模式，可以选择 PKCS1 或 OAEP 模式，不支持 PSS 模式，在对安全场景要求较高的情况下，推荐使用 OAEP 填充模式。 + * @throws CryptoException - 设置填充模式失败或解密失败，抛出异常。 + */ public func decrypt(input: InputStream, output: OutputStream, padType!: PadOption): Unit + + /** + * 将私钥编码为 DER 格式。 + * @return DerBlob - 编码后的DER格式私钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToDer(): DerBlob + + /** + * 使用 AES-256-CBC 加密私钥，将私钥编码为 DER 格式。 + * @param password!: ?String - 加密私钥需要提供的密码，密码为 None 时则不加密。 + * @return DerBlob - 编码后的DER格式私钥。 + * @throws CryptoException - 编码失败、加密失败或者参数密码为空字符串，抛出异常。 + */ public func encodeToDer(password!: ?String): DerBlob + + /** + * 将私钥编码为 PEM 格式。 + * @return PemEntry - 私钥PEM 格式的对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToPem(): PemEntry + + /** + * 对数据的摘要结果进行签名。 + * @param hash: Digest - 摘要方法，获取 digest 结果使用的摘要方法。 + * @param digest: Array - 数据的摘要结果。 + * @param padType!: PadOption - 填充模式，可以选择 PKCS1 或 PSS 模式，不支持 OAEP 模式，在对安全场景要求较高的情况下，推荐使用 PSS 填充模式。 + * @return Array - 签名后的数据。 + * @throws CryptoException - 设置摘要方法失败、设置填充模式失败或签名失败，抛出异常。 + */ public func sign(hash: Digest, digest: Array, padType!: PadOption): Array + + /** + * 输出私钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String } +/** + * RSA 公钥类，提供生成 RSA 公钥能力，RSA 公钥支持验证签名和加密操作，支持 PEM 和 DER 格式的编码解码。 +*/ public class RSAPublicKey <: PublicKey { + /** + * init 初始化公钥，从私钥中获取对应的公钥。 + * @param pri: RSAPrivateKey - RSA私钥。 + * @throws CryptoException - 初始化失败，抛出异常。 + */ public init(pri: RSAPrivateKey) + + /** + * 将公钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的公钥对象。 + * @return RSAPublicKey - 解码出的 RSA 公钥。 + * @throws CryptoException - 解码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): RSAPublicKey + + /** + * 将公钥从PEM 格式解码。 + * @param text: String - PEM 格式的公钥字符流。 + * @return RSAPublicKey - 解码出的 RSA 公钥。 + * @throws CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): RSAPublicKey + + /** + * 将公钥编码为 DER 格式。 + * @return DerBlob - 编码后的Der格式公钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToDer(): DerBlob + + /** + * 将公钥编码为 PEM 格式。 + * @return PemEntry - 返回 PemEntry 对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public override func encodeToPem(): PemEntry + + /** + * encrypt 给一段数据进行加密。 + * @param input: InputStream - 需要加密的数据。 + * @param output: OutputStream - 加密后的数据。 + * @param padType!: PadOption - 填充模式，可以选择 PKCS1 或 OAEP 模式，不支持 PSS 模式，在对安全场景要求较高的情况下，推荐使用 OAEP 填充模式。 + * @throws CryptoException - 设置填充模式失败或加密失败，抛出异常。 + */ public func encrypt(input: InputStream, output: OutputStream, padType!: PadOption): Unit + + /** + * 输出公钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String + + /** + * verify 验证签名结果。 + * @param hash: Digest - 摘要方法，获取 digest 结果使用的摘要方法。 + * @param digest: Array - 数据的摘要结果。 + * @param sig: Array - 数据的签名结果。 + * @param padType!: PadOption - 填充模式，可以选择 PKCS1 或 PSS 模式，不支持 OAEP 模式，在对安全场景要求较高的情况下，推荐使用 PSS 填充模式。 + * @return Bool - 返回 true 表示验证成功，false 失败。 + * @throws CryptoException - 设置填充模式失败或验证失败，抛出异常。 + */ public func verify(hash: Digest, digest: Array, sig: Array, padType!: PadOption): Bool } +/** + * SM2 私钥类，提供生成 SM2 私钥能力，SM2 私钥支持签名和解密操作，支持 PEM 和 DER 格式的编码解码，符合 PKCS1 标准。 +*/ public class SM2PrivateKey <: PrivateKey { + /** + * init 初始化生成私钥。 + * @throws CryptoException - 初始化失败，抛出异常。 + */ public init() + + /** + * 将私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @return SM2PrivateKey - 解码出的 SM2 私钥。 + * @throws CryptoException - 解码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): SM2PrivateKey + + /** + * 将加密的私钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的私钥对象。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return SM2PrivateKey - 解码出的 SM2 私钥。 + * @throws CryptoException - 解码失败、解密失败或者参数密码为空字符串，抛出异常。 + */ public static func decodeDer(blob: DerBlob, password!: ?String): SM2PrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @return SM2PrivateKey - 解码出的 SM2 私钥。 + * @throws CryptoException - 解码失败、解密失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): SM2PrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @param password!: ?String - 解密私钥需要提供的密码，密码为 None 时则不解密。 + * @return SM2PrivateKey - 解码出的 SM2 私钥。 + * @throws CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String, password!: ?String): SM2PrivateKey + + /** + * decrypt 解密出原始数据。 + * @param input: Array - 加密的数据。 + * @return Array - 解密后的数据。 + * @throws CryptoException - 解密失败，抛出异常。 + */ public func decrypt(input: Array): Array + + /** + * 将私钥编码为 DER 格式。 + * @return DerBlob - 编码后的DER格式私钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public func encodeToDer(): DerBlob + + /** + * 使用 AES-256-CBC 加密私钥，将私钥编码为 DER 格式。 + * @param password!: ?String - 加密私钥需要提供的密码，密码为 None 时则不加密。 + * @return DerBlob - 编码后的DER格式公钥。 + * @throws CryptoException - 编码失败、加密失败或者参数密码为空字符串，抛出异常。 + */ public func encodeToDer(password!: ?String): DerBlob + + /** + * 将加密的私钥编码为 PEM 格式。 + * @param password!: ?String - 加密私钥需要提供的密码，密码为 None 时则不加密。 + * @return PemEntry - 私钥PEM 格式的对象。 + * @throws CryptoException - 编码失败、加密失败或者参数密码为空字符串，抛出异常。 + */ public func encodeToPem(password!: ?String): PemEntry + + /** + * 将私钥编码为 PEM 格式。 + * @return PemEntry - 私钥PEM 格式的对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public func encodeToPem(): PemEntry + + /** + * sign 对数据进行签名, SM2采用SM3数据摘要算法。 + * @param data: Array - 数据。 + * @return Array - 签名后的数据。 + * @throws CryptoException - 签名失败，抛出异常。 + */ public func sign(data: Array): Array + + /** + * 输出私钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String } +/** + * SM2 公钥类，提供生成 SM2 公钥能力，SM2 公钥支持验证签名和加密操作，支持 PEM 和 DER 格式的编码解码。 +*/ public class SM2PublicKey <: PublicKey { + /** + * init 初始化公钥，从私钥中获取对应的公钥。 + * @param pri: SM2PrivateKey - SM2 私钥。 + * @throws CryptoException - 初始化失败，抛出异常。 + */ public init(pri: SM2PrivateKey) + + /** + * 将公钥从 DER 格式解码。 + * @param blob: DerBlob - 二进制格式的公钥对象。 + * @return SM2PublicKey - 解码出的 SM2 公钥。 + * @throws CryptoException - 解码失败，抛出异常。 + */ public static func decodeDer(blob: DerBlob): SM2PublicKey + + /** + * 将公钥从PEM 格式解码。 + * @param text: String - PEM 格式的公钥字符流。 + * @return SM2PublicKey - 解码出的 SM2 公钥。 + * @throws CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时，抛出异常。 + */ public static func decodeFromPem(text: String): SM2PublicKey + + /** + * 将公钥编码为 DER 格式。 + * @return DerBlob - 编码后的Der格式公钥。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public func encodeToDer(): DerBlob + + /** + * 将公钥编码为 PEM 格式。 + * @return PemEntry - 返回 PemEntry 对象。 + * @throws CryptoException - 编码失败，抛出异常。 + */ public func encodeToPem(): PemEntry + + /** + * encrypt 给一段数据进行加密。 + * @param input: Array - 需要加密的数据。 + * @return Array - 加密后的数据。 + * @throws CryptoException - 加密失败，抛出异常。 + */ public func encrypt(input: Array): Array + + /** + * 输出公钥种类。 + * @return String - 密钥类别描述。 + */ public override func toString(): String + + /** + * verify 验证签名结果。 + * @param data: Array - 数据。 + * @param sig: Array - 数据的签名结果。 + * @return Bool - 返回 true 表示验证成功，false 失败。 + * @throws CryptoException - 设置填充模式失败或验证失败，抛出异常。 + */ public func verify(data: Array, sig: Array): Bool } @@ -82,32 +476,103 @@ public class SM2PublicKey <: PublicKey { // --------------------------- // -----enums // --------------------------- +/** + * 枚举类型 Curve 用于选择生成 ECDSA 密钥时使用的椭圆曲线类型。 + * 椭圆曲线是一种数学曲线，常用于加密算法中的密钥生成。在密码学中，椭圆曲线密码算法是一种基于椭圆曲线的公钥密码算法。它的基本思想是利用椭圆曲线上的点集构成一个计算困难性，来实现公钥密码的安全性。 + * Curve 枚举类型支持 NIST P-224，NIST P-256，NIST P-384，NIST P-521，Brainpool P-256，Brainpool P-320，Brainpool P-384，Brainpool P-512 八种椭圆曲线。 +*/ public enum Curve { - BP256 - BP320 - BP384 - BP512 - P224 - P256 - P384 - P521 + /** + * 使用 Brainpool P-256 椭圆曲线初始化 Curve 实例。 + */ + | BP256 + + /** + * 使用 Brainpool P-320 椭圆曲线初始化 Curve 实例。 + */ + | BP320 + + /** + * 使用 Brainpool P-384 椭圆曲线初始化 Curve 实例。 + */ + | BP384 + + /** + * 使用 Brainpool P-512 椭圆曲线初始化 Curve 实例。 + */ + | BP512 + + /** + * 使用 NIST P-224 椭圆曲线初始化 Curve 实例。 + */ + | P224 + + /** + * 使用 NIST P-256 椭圆曲线初始化 Curve 实例。 + */ + | P256 + + /** + * 使用 NIST P-384 椭圆曲线初始化 Curve 实例。 + */ + | P384 + + /** + * 使用 NIST P-521 椭圆曲线初始化 Curve 实例。 + */ + | P521 } +/** + * 用于设置 RSA 的填充模式。 + * RSA 有三种常用的填充模式： + * OAEP 为最优非对称加密填充，只能用于加密解密； PSS 为概率签名方案，只能用于签名和验证； PKCS1 是一种普通的填充模式，用于填充数据长度，可以用于加密、解密、签名和验证。 RSA 的 PKCS1 填充模式是在早期的 PKCS #1 v1.5 规范中定义的填充模式，当前对使用 PKCS1 填充模式的攻击较为成熟，容易被攻击者解密或伪造签名，建议采用 PKCS #1 v2 版本中更加安全的 PSS 或 OAEP 填充模式。 +*/ public enum PadOption { - OAEP(OAEPOption) - PKCS1 - PSS(PSSOption) + /** + * 使用最优非对称加密初始化 PadOption 实例。 + */ + | OAEP(OAEPOption) + + /** + * 使用 PKCS #1 公钥密码学标准初始化 PadOption 实例。 + */ + | PKCS1 + + /** + * 使用概率签名方案初始化 PadOption 实例。 + */ + | PSS(PSSOption) } // --------------------------- // -----structs // --------------------------- +/** + * 此结构体为 OAEP 填充模式需要设置的参数。 +*/ public struct OAEPOption { + /** + * 初始化 OAEP 填充参数。 + * @param hash: Digest - 摘要方法，用于对 label 进行摘要。 + * @param mgfHash: Digest - 摘要方法，用于设置 MGF1 函数中的摘要方法。 + * @param label!: String - label 是可选参数，默认为空字符串，可以通过设置 label 来区分不同的加密操作。 + */ public init(hash: Digest, mgfHash: Digest, label!: String = "") + + /** + * 初始化 OAEP 填充参数。 + * @param hash: Digest - 摘要方法，用于对 label 进行摘要。 + * @param mgfHash: Digest- 摘要方法，用于设置 MGF1 函数中的摘要方法。 + * @param label!: String - 摘要方法，label 是可选参数，默认为空字符串，可以通过设置 label 来区分不同的加密操作。 + */ public init(hash: Digest, mgfHash: Digest, label!: String = "") } +/** + * 此结构体为 PSS 填充模式需要设置的参数。 +*/ public struct PSSOption {} diff --git a/cangjie_libs/crypto/x509.cjd b/cangjie_libs/crypto/x509.cjd index 256723f..f2d9797 100644 --- a/cangjie_libs/crypto/x509.cjd +++ b/cangjie_libs/crypto/x509.cjd @@ -3,61 +3,312 @@ package crypto.x509 // --------------------------- // -----classes // --------------------------- +/** + * X509 数字证书是一种用于加密通信的数字证书，它是公钥基础设施（PKI）的核心组件之一。X509 数字证书包含了一个实体的公钥和身份信息，用于验证该实体的身份和确保通信的安全性。 +*/ public class X509Certificate <: Equatable & Hashable & ToString { + /** + * 解析数字证书备选名称中的域名。 + */ public prop dnsNames: Array + + /** + * 解析数字证书备选名称中的 email 地址。 + */ public prop emailAddresses: Array + + /** + * 解析数字证书中的扩展密钥用法。 + */ public prop extKeyUsage: ExtKeyUsage + + /** + * 解析数字证书的颁发者信息。 + */ public prop issuer: X509Name + + /** + * 解析数字证书备选名称中的 IP 地址。 + */ public prop IPAddresses: Array + + /** + * 解析数字证书中的密钥用法。 + */ public prop keyUsage: KeyUsage + + /** + * 解析数字证书的有效期截止时间。 + */ public prop notAfter: DateTime + + /** + * 解析数字证书的有效期开始时间。 + */ public prop notBefore: DateTime + + /** + * 解析数字证书的公钥。 + */ public prop publicKey: PublicKey + + /** + * 解析数字证书的公钥算法。 + */ public prop publicKeyAlgorithm: PublicKeyAlgorithm + + /** + * 解析数字证书的序列号。 + */ public prop serialNumber: SerialNumber + + /** + * 解析数字证书的签名。 + */ public prop signature: Signature + + /** + * 解析数字证书的签名算法。 + */ public prop signatureAlgorithm: SignatureAlgorithm + + /** + * 解析数字证书的使用者信息。 + */ public prop subject: X509Name + + /** + * 创建数字证书对象。 + * @param certificateInfo: X509CertificateInfo - 数字证书配置信息。 + * @param parent!: X509Certificate - 颁发者证书。 + * @param publicKey!: PublicKey - 申请人公钥，仅支持 RSA、ECDSA 和 DSA 公钥。 + * @param privateKey!: PrivateKey - 颁发者私钥，仅支持 RSA、ECDSA 和 DSA 私钥。 + * @param signatureAlgorithm!: ?SignatureAlgorithm - 证书签名算法，默认值为 None，使用默认值时默认的摘要类型是 SHA256。 + * @throws X509Exception - 公钥或私钥类型不支持、私钥类型和证书签名算法中的私钥类型不匹配或数字证书信息设置失败时，抛出异常。 + */ public init( certificateInfo: X509CertificateInfo, parent!: X509Certificate, publicKey!: PublicKey, privateKey!: PrivateKey, signatureAlgorithm!: ?SignatureAlgorithm = None) + + /** + * 将 DER 格式的数字证书解码。 + * @param der: DerBlob - DER 格式的二进制数据。 + * @return X509Certificate - 由 DER 格式解码出的数字证书。 + * @throws X509Exception - 数据为空时，或数据不是有效的数字证书 DER 格式时抛出异常。 + */ public static func decodeFromDer(der: DerBlob): X509Certificate + + /** + * 将数字证书从 PEM 格式解码。 + * @param pem: String - PEM 格式的数字证书字符流。 + * @return Array - 由 PEM 格式解码出的数字证书数组。 + * @throws X509Exception - 字符流不符合 PEM 格式时，或文件头不符合数字证书头标准时抛出异常。 + */ public static func decodeFromPem(pem: String): Array + + /** + * 将数字证书编码成 Der 格式。 + * @return DerBlob - 编码后的 Der 格式的数字证书。 + */ public func encodeToDer(): DerBlob + + /** + * 将数字证书编码成 PEM 格式。 + * @return PemEntry - 编码后的 PEM 格式的数字证书。 + */ public func encodeToPem(): PemEntry + + /** + * 返回证书哈希值。 + * @return Int64 - 对证书对象进行哈希计算后得到的结果。 + */ public override func hashCode(): Int64 + + /** + * 返回操作系统的根证书，支持 Linux，MacOS 和 Windows 平台。 + * @return Array - 操作系统的根证书链。 + */ public static func systemRootCerts(): Array + + /** + * 生成证书名称字符串，包含证书的使用者信息、有效期以及颁发者信息。 + * @return String - 证书名称字符串。 + */ public override func toString(): String + + /** + * 根据验证选项验证当前证书的有效性。 + * 验证优先级： + * @param verifyOption: VerifyOption - 证书验证选项。 + * @return Bool - 证书有效返回 true，否则返回 false。 + * @throws X509Exception - 检验过程中失败，比如内存分配异常等内部错误，则抛出异常。 + */ public func verify(verifyOption: VerifyOption): Bool + + /** + * 判不等。 + * @param other: X509Certificate - 被比较的证书对象。 + * @return Bool - 若证书不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: X509Certificate): Bool + + /** + * 判等。 + * @param other: X509Certificate - 被比较的证书对象。 + * @return Bool - 若证书相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: X509Certificate): Bool } +/** + * 数字证书签名请求。 +*/ public class X509CertificateRequest <: Hashable & ToString { + /** + * 解析数字证书签名请求备选名称中的 IP 地址。 + */ public prop IPAddresses: Array + + /** + * 解析数字证书签名请求备选名称中的域名。 + */ public prop dnsNames: Array + + /** + * 解析数字证书签名请求备选名称中的 email 地址。 + */ public prop emailAddresses: Array + + /** + * 解析数字证书签名请求的公钥。 + */ public prop publicKey: PublicKey + + /** + * 解析数字证书签名请求的公钥算法。 + */ public prop publicKeyAlgorithm: PublicKeyAlgorithm + + /** + * 解析数字证书签名请求的签名。 + */ public prop signature: Signature + + /** + * 解析数字证书签名请求的签名算法。 + */ public prop signatureAlgorithm: SignatureAlgorithm + + /** + * 解析数字证书签名请求的使用者信息。 + */ public prop subject: X509Name + + /** + * 创建数字证书签名请求对象。 + * @param privateKey: PrivateKey - 私钥，仅支持 RSA、ECDSA 和 DSA 私钥。 + * @param certificateRequestInfo!: ?X509CertificateRequestInfo - 数字证书签名信息，默认值为 None。 + * @param signatureAlgorithm!: ?SignatureAlgorithm - 证书签名算法，默认值为 None，使用默认值时默认的摘要类型是 SHA256。 + * @throws X509Exception - 私钥类型不支持、私钥类型和证书签名算法中的私钥类型不匹配或数字证书签名信息设置失败时，抛出异常。 + */ public init( privateKey: PrivateKey, certificateRequestInfo!: ?X509CertificateRequestInfo = None, signatureAlgorithm!: ?SignatureAlgorithm = None) + + /** + * 将 DER 格式的数字证书签名请求解码。 + * @param der: DerBlob - DER 格式的二进制数据。 + * @return X509CertificateRequest - 由 DER 格式解码出的数字证书签名请求。 + * @throws X509Exception - 数据为空时，或数据不是有效的数字证书签名请求 DER 格式时抛出异常。 + */ public static func decodeFromDer(der: DerBlob): X509CertificateRequest + + /** + * 将数字证书签名请求从 PEM 格式解码。 + * @param pem: String - PEM 格式的数字证书签名请求字符流。 + * @return Array - 由 PEM 格式解码出的数字证书签名请求数组。 + * @throws X509Exception - 字符流不符合 PEM 格式时，或文件头不符合数字证书签名请求头标准时抛出异常。 + */ public static func decodeFromPem(pem: String): Array + + /** + * 将数字证书签名请求编码成 Der 格式。 + * @return DerBlob - 编码后的 Der 格式的数字证书签名请求。 + */ public func encodeToDer(): DerBlob + + /** + * 将数字证书签名请求编码成 PEM 格式。 + * @return PemEntry - 编码后的 PEM 格式的数字证书签名请求。 + */ public func encodeToPem(): PemEntry + + /** + * 返回证书签名请求哈希值。 + * @return Int64 - 对证书签名请求对象进行哈希计算后得到的结果。 + */ public override func hashCode(): Int64 + + /** + * 生成证书签名请求名称字符串，包含证书签名请求的使用者信息。 + * @return String - 证书签名请求名称字符串。 + */ public override func toString(): String } +/** + * 证书实体可辨识名称（Distinguished Name）是数字证书中的一个重要组成部分，作用是确保证书的持有者身份的真实性和可信度，同时也是数字证书验证的重要依据之一。 + * X509Name 通常包含证书实体的国家或地区名称（Country Name）、州或省名称（State or Province Name）、城市名称（Locality Name）、组织名称（Organization Name）、组织单位名称（Organizational Unit Name）、通用名称（Common Name）。有时也会包含 email 地址。 +*/ public class X509Name <: ToString { + /** + * 返回证书实体的通用名称。 + */ public prop commonName: ?String + + /** + * 返回证书实体的国家或地区名称。 + */ public prop countryName: ?String + + /** + * 返回证书实体的 email 地址。 + */ public prop email: ?String + + /** + * 返回证书实体的城市名称。 + */ public prop localityName: ?String + + /** + * 返回证书实体的组织名称。 + */ public prop organizationName: ?String + + /** + * 返回证书实体的组织单位名称。 + */ public prop organizationalUnitName: ?String + + /** + * 返回证书实体的州或省名称。 + */ public prop provinceName: ?String + + /** + * 构造 X509Name 对象。 + * @param countryName!: ?String - 国家或地区名称，默认值为 None。 + * @param provinceName!: ?String - 州或省名称，默认值为 None。 + * @param localityName!: ?String - 城市名称，默认值为 None。 + * @param organizationName!: ?String - 组织名称，默认值为 None。 + * @param organizationalUnitName!: ?String - 组织单位名称，默认值为 None。 + * @param commonName!: ?String - 通用名称，默认值为 None。 + * @param email!: ?String - email 地址，默认值为 None。 + * @throws X509Exception - 设置证书实体可辨识名称时失败，比如内存分配异常等内部错误，则抛出异常。 + */ public init( countryName!: ?String = None, provinceName!: ?String = None, localityName!: ?String = None, organizationName!: ?String = None, organizationalUnitName!: ?String = None, commonName!: ?String = None, email!: ?String = None ) + + /** + * 生成证书实体名称字符串。 + * @return String - 证书实体名称字符串，包含实体名称中存在的字段信息。 + */ public override func toString(): String } @@ -65,32 +316,139 @@ public class X509Name <: ToString { // --------------------------- // -----enums // --------------------------- +/** + * 数字证书中包含的公钥信息，目前支持的种类有：RSA、DSA、ECDSA。 +*/ public enum PublicKeyAlgorithm <: Equatable & ToString { - DSA - ECDSA - RSA - UnknownPublicKeyAlgorithm + /** + * DSA 公钥算法。 + */ + | DSA + + /** + * ECDSA 公钥算法。 + */ + | ECDSA + + /** + * RSA 公钥算法。 + */ + | RSA + + /** + * 未知公钥算法。 + */ + | UnknownPublicKeyAlgorithm + + /** + * 生成证书携带的公钥算法名称字符串。 + * @return String - 证书携带的公钥算法名称字符串。 + */ public override func toString(): String + + /** + * 判不等。 + * @param other: PublicKeyAlgorithm - 被比较的公钥算法。 + * @return Bool - 若公钥算法不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: PublicKeyAlgorithm): Bool + + /** + * 判等。 + * @param other: PublicKeyAlgorithm - 被比较的公钥算法。 + * @return Bool - 若公钥算法相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: PublicKeyAlgorithm): Bool } +/** + * 证书签名算法（Signature Algorithm）是用于数字证书签名的算法，它是一种将数字证书中的公钥和其他信息进行加密的算法，以确保数字证书的完整性和真实性。 + * 目前支持签名算法的种类包括：MD2WithRSA 、MD5WithRSA 、SHA1WithRSA 、SHA256WithRSA 、SHA384WithRSA、SHA512WithRSA、DSAWithSHA1、DSAWithSHA256、ECDSAWithSHA1、ECDSAWithSHA256、ECDSAWithSHA384 和 ECDSAWithSHA512。 +*/ public enum SignatureAlgorithm <: Equatable & ToString { - DSAWithSHA1 - DSAWithSHA256 - ECDSAWithSHA1 - ECDSAWithSHA256 - ECDSAWithSHA384 - ECDSAWithSHA512 - MD2WithRSA - MD5WithRSA - SHA1WithRSA - SHA256WithRSA - SHA384WithRSA - SHA512WithRSA - UnknownSignatureAlgorithm + /** + * DSAwithSHA1 签名算法。 + */ + | DSAWithSHA1 + + /** + * DSAwithSHA256 签名算法。 + */ + | DSAWithSHA256 + + /** + * ECDSAwithSHA1 签名算法。 + */ + | ECDSAWithSHA1 + + /** + * ECDSAwithSHA256 签名算法。 + */ + | ECDSAWithSHA256 + + /** + * ECDSAwithSHA384 签名算法。 + */ + | ECDSAWithSHA384 + + /** + * ECDSAwithSHA512 签名算法。 + */ + | ECDSAWithSHA512 + + /** + * MD2withRSA 签名算法。 + */ + | MD2WithRSA + + /** + * MD5withRSA 签名算法。 + */ + | MD5WithRSA + + /** + * SHA1withRSA签名算法。 + */ + | SHA1WithRSA + + /** + * SHA256withRSA 签名算法。 + */ + | SHA256WithRSA + + /** + * SHA384withRSA 签名算法。 + */ + | SHA384WithRSA + + /** + * SHA512withRSA 签名算法。 + */ + | SHA512WithRSA + + /** + * 未知签名算法。 + */ + | UnknownSignatureAlgorithm + + /** + * 生成证书签名算法名称字符串。 + * @return String - 证书签名算法名称字符串。 + */ public override func toString(): String + + /** + * 判不等。 + * @param other: SignatureAlgorithm - 被比较的签名算法。 + * @return Bool - 若签名算法不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: SignatureAlgorithm): Bool + + /** + * 判等。 + * @param other: SignatureAlgorithm - 被比较的签名算法。 + * @return Bool - 若签名算法相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: SignatureAlgorithm): Bool } @@ -98,8 +456,19 @@ public enum SignatureAlgorithm <: Equatable & ToString { // --------------------------- // -----exceptions // --------------------------- +/** + * 此异常为 X509 包抛出的异常类型。 +*/ public class X509Exception <: Exception { + /** + * 构造 X509Exception 对象。 + */ public init() + + /** + * 构造 X509Exception 对象。 + * @param message: String - 异常的信息。 + */ public init(message: String) } @@ -107,32 +476,151 @@ public class X509Exception <: Exception { // --------------------------- // -----interfaces // --------------------------- +/** + * 提供 DH 参数接口。 +*/ public interface DHParamters <: Key { + /** + * 将 DH 密钥参数从 DER 格式解码。 + * @param blob: DerBlob - DER 格式的 DH 密钥参数对象。 + * @return DHParamters - 由 DER 格式解码出的 DH 密钥参数。 + * @throws X509Exception - 当 DER 格式的 DH 密钥参数内容不正确，无法解析时抛出异常。 + */ static func decodeDer(blob: DerBlob): DHParamters + + /** + * 将 DH 密钥参数从 PEM 格式解码。 + * @param text: String - PEM 格式的 DH 密钥参数字符流。 + * @return DHParamters - 由 PEM 格式解码出的 DH 密钥参数。 + * @throws X509Exception - 字符流不符合 PEM 格式时，或文件头不符合 DH 密钥参数头标准 ("-----BEGIN DH PARAMETERS-----")时抛出异常。 + */ static func decodeFromPem(text: String): DHParamters + + /** + * 将 DH 密钥参数编码为 PEM 格式。 + * @return PemEntry - DH 密钥参数数据 PEM 格式编码生成的对象。 + */ override func encodeToPem(): PemEntry } +/** + * 提供密钥接口。 公钥用于签名验证或加密，私钥用于签名或解密，公钥和私钥必须相互匹配并形成一对。 该类为密钥类，无具体实现，供 PrivateKey/PublicKey 及用户扩展接口。 +*/ public interface Key <: ToString { + /** + * 将密钥从 DER 格式解码。 + * @param encoded: DerBlob - DER 格式的对象。 + * @return Key - 由 DER 格式解码出的密钥。 + * @throws X509Exception - 当 DER 格式的私钥内容不正确，无法解析时抛出异常。 + */ static func decodeDer(encoded: DerBlob): Key + + /** + * 将密钥从 PEM 格式解码。 + * @param text: String - PEM 格式的字符流。 + * @return Key - 由 PEM 格式解码出的密钥。 + */ static func decodeFromPem(text: String): Key + + /** + * 将密钥编码为 DER 格式。 + * @return DerBlob - 密钥数据 DER 格式编码生成的对象。 + */ func encodeToDer(): DerBlob + + /** + * 将密钥编码为 PEM 格式。 + * @return PemEntry - 密钥数据 PEM 格式编码生成的对象。 + */ func encodeToPem(): PemEntry } +/** + * 提供私钥接口。 +*/ public interface PrivateKey <: Key { + /** + * 将私钥从 DER 格式解码。 + * @param blob: DerBlob - DER 格式的私钥对象。 + * @return PrivateKey - 由 DER 格式解码出的私钥。 + * @throws X509Exception - 当 DER 格式的私钥内容不正确，无法解析时抛出异常。 + */ static func decodeDer(blob: DerBlob): PrivateKey + + /** + * 将 DER 格式的私钥解密解码成 PrivateKey 对象，密码为 None 时则不解密。 + * @param blob: DerBlob - DER 格式的私钥。 + * @param password!: ?String - 解密密码。 + * @return PrivateKey - 解密解码后的私钥对象。 + * @throws X509Exception - 解密解码失败，或者 password 为空字符串。 + */ static func decodeDer(blob: DerBlob, password!: ?String): PrivateKey + + /** + * 将私钥从 PEM 格式解码。 + * @param text: String - PEM 格式的私钥字符流。 + * @return PrivateKey - 由 PEM 格式解码出的私钥。 + * @throws X509Exception - 字符流不符合 PEM 格式时，或文件头不符合公钥头标准时抛出异常。 + */ static func decodeFromPem(text: String): PrivateKey + + /** + * 将 PEM 格式的私钥解密解码成 PrivateKey 对象，密码为 None 时则不解密。 + * @param text: String - PEM 格式的私钥。 + * @param password!: ?String - 解密密码。 + * @return PrivateKey - 解密解码后的私钥对象。 + * @throws X509Exception - 解密解码失败，或者 password 为空字符串。 + */ static func decodeFromPem(text: String, password!: ?String): PrivateKey + + /** + * 将私钥加密编码成 DER 格式，密码为 None 时则不加密。 + * @param password!: ?String - 加密密码。 + * @return DerBlob - 加密后的 DER 格式的私钥。 + * @throws X509Exception - 加密失败，或者 password 为空字符串。 + */ func encodeToDer(password!: ?String): DerBlob + + /** + * 将私钥编码成 PEM 格式。 + * @return PemEntry - 编码后的 PEM 格式的私钥。 + * @throws X509Exception - 编码失败。 + */ override func encodeToPem(): PemEntry + + /** + * 将私钥加密编码成 PEM 格式，密码为 None 时则不加密。 + * @param password!: ?String - 加密密码。 + * @return PemEntry - 加密后的 PEM 格式的私钥。 + * @throws X509Exception - 加密失败，或者 password 为空字符串。 + */ func encodeToPem(password!: ?String): PemEntry } +/** + * 公钥接口接口。 +*/ public interface PublicKey <: Key { + /** + * 将公钥从 DER 格式解码。 + * @param blob: DerBlob - DER 格式的公钥对象。 + * @return PublicKey - 由 DER 格式解码出的公钥。 + * @throws X509Exception - 当 DER 格式的公钥内容不正确，无法解析时抛出异常。 + */ static func decodeDer(blob: DerBlob): PublicKey + + /** + * 将公钥从 PEM 格式解码。 + * @param text: String - PEM 格式的公钥字符流。 + * @return PublicKey - 由 PEM 格式解码出的公钥。 + * @throws X509Exception - 字符流不符合 PEM 格式时，或文件头不符合公钥头标准时抛出异常。 + */ static func decodeFromPem(text: String): PublicKey + + /** + * 将公钥编码为 PEM 格式。 + * @return PemEntry - 公钥数据 PEM 格式编码生成的对象。 + */ override func encodeToPem(): PemEntry } @@ -140,113 +628,506 @@ public interface PublicKey <: Key { // --------------------------- // -----structs // --------------------------- +/** + * Crypto 支持配置二进制证书流，用户读取二进制证书数据并创建 DerBlob 对象后可将其解析成 X509Certificate / X509CertificateRequest / PublicKey / PrivateKey 对象。 +*/ public struct DerBlob <: Equatable & Hashable { + /** + * DerBlob 对象中的字符序列。 + */ public prop body: Array + + /** + * DerBlob 对象中字符序列的大小。 + */ public prop size: Int64 + + /** + * 构造 DerBlob 对象。 + * @param content: Array - 二进制字符序列。 + */ public init(content: Array) + + /** + * 返回 DerBlob 对象哈希值。 + * @return Int64 - 对 DerBlob 对象进行哈希计算后得到的结果。 + */ public override func hashCode(): Int64 + + /** + * 判不等。 + * @param other: DerBlob - 被比较的 DerBlob 对象。 + * @return Bool - 若对象不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: DerBlob): Bool + + /** + * 判等。 + * @param other: DerBlob - 被比较的 DerBlob 对象。 + * @return Bool - 若对象相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: DerBlob): Bool } +/** + * 数字证书扩展字段中通常会包含携带扩展密钥用法说明，目前支持的用途有：ServerAuth、ClientAuth、EmailProtection、CodeSigning、OCSPSigning、TimeStamping。 +*/ public struct ExtKeyUsage <: ToString { + /** + * 表示应用于任意用途。 + */ public static let AnyKey = 0u16 + + /** + * 表示用于 SSL 的客户端验证。 + */ public static let ClientAuth = 2u16 + + /** + * 表示用于代码签名。 + */ public static let CodeSigning = 4u16 + + /** + * 表示用于电子邮件的加解密、签名等。 + */ public static let EmailProtection = 3u16 + + /** + * 用于对 OCSP 响应包进行签名。 + */ public static let OCSPSigning = 5u16 + + /** + * 表示用于 SSL 的服务端验证。 + */ public static let ServerAuth = 1u16 + + /** + * 用于将对象摘要值与时间绑定。 + */ public static let TimeStamping = 6u16 + + /** + * 构造指定用途的扩展密钥用法，需要注意同一个密钥可以有多种用途。 + * @param keys: Array - 密钥。 + */ public init(keys: Array) + + /** + * 生成扩展密钥用途字符串。 + * @return String - 证书扩展密钥用途字符串。 + */ public override func toString(): String } +/** + * 数字证书扩展字段中通常会包含携带公钥的用法说明，目前支持的用途有：DigitalSignature、NonRepudiation、KeyEncipherment、DataEncipherment、KeyAgreement、CertSign、CRLSign、EncipherOnly、DecipherOnly。 +*/ public struct KeyUsage <: ToString { + /** + * 表示私钥可用于对 CRL 签名，而公钥可用于验证 CRL 签名。 + */ public static let CRLSign = 0x0002u16 + + /** + * 表示私钥用于证书签名，而公钥用于验证证书签名，专用于 CA 证书。 + */ public static let CertSign = 0x0004u16 + + /** + * 表示公钥用于直接加密数据。 + */ public static let DataEncipherment = 0x0010u16 + + /** + * 表示证书中的公钥在密钥协商过程中，仅仅用于解密计算，配合 key Agreement 使用才有意义。 + */ public static let DecipherOnly = 0x0100u16 + + /** + * 表示私钥可以用于除了签发证书、签发 CRL 和非否认性服务的各种数字签名操作,而公钥用来验证这些签名。 + */ public static let DigitalSignature = 0x0080u16 + + /** + * 表示证书中的公钥在密钥协商过程中，仅仅用于加密计算，配合 key Agreement 使用才有意义。 + */ public static let EncipherOnly = 0x0001u16 + + /** + * 表示密钥用于密钥协商。 + */ public static let KeyAgreement = 0x0008u16 + + /** + * 表示密钥用来加密传输其他的密钥。 + */ public static let KeyEncipherment = 0x0020u16 + + /** + * 表示私钥可以用于进行非否认性服务中的签名,而公钥用来验证签名。 + */ public static let NonRepudiation = 0x0040u16 + + /** + * 构造指定用途的扩展密钥用法，需要注意同一个密钥可以有多种用途。 + * @param keys: UInt16 - 密钥的用法，建议使用本结构中所提供的密钥用法变量通过按位或的方式传入参数。 + */ public init(keys: UInt16) + + /** + * 生成密钥用途字符串。 + * @return String - 证书密钥用途字符串。 + */ public override func toString(): String } +/** + * 结构体 Pem 为条目序列，可以包含多个 PemEntry。 +*/ public struct Pem <: Collection & ToString { + /** + * 条目序列的数量。 + */ public override prop size: Int64 + + /** + * 构造 Pem 对象。 + * @param items: Array - 多个 PemEntry 对象。 + */ public Pem(private let items: Array) + + /** + * 将 PEM 文本解码为条目序列。 + * @param text: String - PEM 字符串。 + * @return Pem - PEM 条目序列。 + */ public static func decode(text: String): Pem + + /** + * 返回PEM格式的字符串。行结束符将根据当前操作系统生成。 + * @return String - PEM 格式的字符串。 + */ public func encode(): String + + /** + * 判断 PEM 文本解码为条目序列是否为空。 + * @return Bool - PEM 文本解码为条目序列为空返回 true；否则，返回 false。 + */ public override func isEmpty(): Bool + + /** + * 生成 PEM 文本解码为条目序列的迭代器。 + * @return Iterator - PEM 文本解码为条目序列的迭代器。 + */ public override func iterator(): Iterator + + /** + * 返回一个字符串，字符串内容是包含每个条目序列的标签。 + * @return String - 包含每个条目序列的标签的字符串。 + */ public override func toString(): String } +/** + * PEM 文本格式经常用于存储证书和密钥，PEM 编码结构包含以下几个部分： + * 第一行是 “-----BEGIN”，标签和 “-----” 组成的utf8编码的字符串； 中间是正文，是实际二进制内容经过 base64 编码得到的可打印字符串，详细的PEM编码规范可参考 RFC 7468； 最后一行是 “-----END”，标签和 “-----” 组成的 utf8 编码的字符串，详见 RFC 1421。 在旧版的 PEM 编码标准中在第一行和正文之间还包含条目头。 + * 为了支持不同的用户场景，我们提供了 PemEntry 和 Pem 类型，PemEntry 用于存储单个PEM 基础结构。 +*/ public struct PemEntry <: ToString { + /** + * 记录条目类型为证书。 + */ public static let LABEL_CERTIFICATE = "CERTIFICATE" + + /** + * 记录条目类型为证书签名请求。 + */ public static let LABEL_CERTIFICATE_REQUEST = "CERTIFICATE REQUEST" + + /** + * 记录条目类型为 DH 密钥参数。 + */ public static let LABEL_DH_PARAMETERS = "DH PARAMETERS" + + /** + * 记录条目类型为椭圆曲线参数。 + */ public static let LABEL_EC_PARAMETERS = "EC PARAMETERS" + + /** + * 记录条目类型为椭圆曲线私钥。 + */ public static let LABEL_EC_PRIVATE_KEY = "EC PRIVATE KEY" + + /** + * 记录条目类型为 PKCS #8 标准加密的私钥。 + */ public static let LABEL_ENCRYPTED_PRIVATE_KEY = "ENCRYPTED PRIVATE KEY" + + /** + * 记录条目类型为 PKCS #8 标准未加密的私钥。 + */ public static let LABEL_PRIVATE_KEY = "PRIVATE KEY" + + /** + * 记录条目类型为公钥。 + */ public static let LABEL_PUBLIC_KEY = "PUBLIC KEY" + + /** + * 记录条目类型为 RSA 私钥。 + */ public static let LABEL_RSA_PRIVATE_KEY = "RSA PRIVATE KEY" + + /** + * 记录条目类型为 SM2 私钥。 + */ public static let LABEL_SM2_PRIVATE_KEY = "SM2 PRIVATE KEY" + + /** + * 记录条目类型为证书吊销列表。 + */ public static let LABEL_X509_CRL = "X509 CRL" + + /** + * 构造 PemEntry 对象。 + * @param label: String - 标签。 + * @param headers: Array<(String, String)> - 条目头。 + * @param body: ?DerBlob - 二进制内容。 + */ public PemEntry( public let label: String, public let headers: Array<(String, String)>, public let body: ?DerBlob) + + /** + * PemEntry 实例的二进制内容。 + */ public let body: ?DerBlob + + /** + * PemEntry 实例的条目头。 + */ public let headers: Array<(String, String)> + + /** + * PemEntry 实例的标签。 + */ public let label: String + + /** + * 构造 PemEntry 对象。 + * @param label: String - 标签 + * @param body: DerBlob - 二进制内容 + */ public init(label: String, body: DerBlob) + + /** + * 返回PEM格式的字符串。行结束符将根据当前操作系统生成。 + * @return String - PEM 格式的字符串。 + */ public func encode(): String + + /** + * 通过条目头名称，找到对应条目内容。 + * @param name: String - 条目头名称。 + * @return Iterator - 条目头名称对应内容的迭代器。 + */ public func header(name: String): Iterator + + /** + * 返回 PEM 对象的标签和二进制内容的长度。 + * @return String - PEM 对象的标签和二进制内容的长度。 + */ public override func toString(): String } +/** + * 结构体 SerialNumber 为数字证书的序列号，是数字证书中的一个唯一标识符，用于标识数字证书的唯一性。根据规范，证书序列号的长度不应超过 20 字节。详见rfc5280。 +*/ public struct SerialNumber <: Equatable & Hashable & ToString { + /** + * 生成指定长度的随机序列号。 + * @param length!: UInt8 - 序列号长度，单位为字节，类型为 UInt8，默认值为 16。 + * @throws X509Exception - length 等于 0 或大于 20 时，抛出异常。 + */ public init(length!: UInt8 = 16) + + /** + * 返回证书序列号哈希值。 + * @return Int64 - 对证书序列号对象进行哈希计算后得到的结果。 + */ public override func hashCode(): Int64 + + /** + * 生成证书序列号字符串，格式为 16 进制。 + * @return String - 证书序列号字符串。 + */ public override func toString(): String + + /** + * 判不等。 + * @param other: SerialNumber - 被比较的证书序列号对象。 + * @return Bool - 若序列号不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: SerialNumber): Bool + + /** + * 判等。 + * @param other: SerialNumber - 被比较的证书序列号对象。 + * @return Bool - 若序列号相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: SerialNumber): Bool } +/** + * 数字证书的签名，用来验证身份的正确性。 +*/ public struct Signature <: Equatable & Hashable { + /** + * 返回证书签名的二进制。 + */ public prop signatureValue: DerBlob + + /** + * 返回证书签名哈希值。 + * @return Int64 - 对证书签名对象进行哈希计算后得到的结果。 + */ public override func hashCode(): Int64 + + /** + * 判不等。 + * @param other: Signature - 被比较的证书签名。 + * @return Bool - 若证书签名不同，返回 true；否则，返回 false。 + */ public override operator func !=(other: Signature): Bool + + /** + * 判等。 + * @param other: Signature - 被比较的证书签名。 + * @return Bool - 若证书签名相同，返回 true；否则，返回 false。 + */ public override operator func ==(other: Signature): Bool } public struct VerifyOption { + /** + * 校验域名，默认为空，只有设置域名时才会进行此处校验。 + */ public var dnsName: String = "" + + /** + * 中间证书链，默认为空。 + */ public var intermediates: Array = Array() + + /** + * 根证书链，默认为系统根证书链。 + */ public var roots: Array = X509Certificate.systemRootCerts() + + /** + * 校验时间，默认为创建选项的时间。 + */ public var time: DateTime = DateTime.now() } +/** + * X509CertificateInfo 结构包含了证书信息，包括证书序列号、有效期、实体可辨识名称、域名、email 地址、IP 地址、密钥用法和扩展密钥用法。 +*/ public struct X509CertificateInfo { + /** + * 记录证书的 IP 地址。 + */ public var IPAddresses: Array + + /** + * 记录证书的 DNS 域名。 + */ public var dnsNames: Array + + /** + * 记录证书的 email 地址。 + */ public var emailAddresses: Array + + /** + * 记录证书的扩展密钥用法。 + */ public var extKeyUsage: ?ExtKeyUsage + + /** + * 记录证书的密钥用法。 + */ public var keyUsage: ?KeyUsage + + /** + * 记录证书有效期的结束日期。 + */ public var notAfter: DateTime + + /** + * 记录证书有效期的起始日期。 + */ public var notBefore: DateTime + + /** + * 记录证书的序列号。 + */ public var serialNumber: SerialNumber + + /** + * 记录证书实体可辨识名称。 + */ public var subject: ?X509Name + + /** + * 构造 X509CertificateInfo 对象。 + * @param serialNumber!: ?SerialNumber - 数字证书序列号，默认值为 None，使用默认值时默认的序列号长度为 128 比特。 + * @param notBefore!: ?DateTime - 数字证书有效期开始时间，默认值为 None，使用默认值时默认的时间为 X509CertificateInfo 创建的时间。 + * @param notAfter!: ?DateTime - 数字证书有效期截止时间，默认值为 None，使用默认值时默认的时间为 notBefore 往后 1 年的时间。 + * @param subject!: ?X509Name - 数字证书使用者信息，默认值为 None。 + * @param dnsNames!: Array - 域名列表，需要用户保证输入域名的有效性，默认值为空的字符串数组。 + * @param emailAddresses!: Array - email 地址列表，需要用户保证输入 email 的有效性，默认值为空的字符串数组。 + * @param IPAddresses!: Array - IP 地址列表，默认值为空的 IP 数组。 + * @param keyUsage!: ?KeyUsage - 密钥用法，默认值为 None。 + * @param extKeyUsage!: ?ExtKeyUsage - 扩展密钥用法，默认值为 None。 + * @throws X509Exception - 输入的 IP 地址列表中包含无效的 IP 地址，则抛出异常。 + */ public init( serialNumber!: ?SerialNumber = None, notBefore!: ?DateTime = None, notAfter!: ?DateTime = None, subject!: ?X509Name = None, dnsNames!: Array = Array(), emailAddresses!: Array = Array(), IPAddresses!: Array = Array(), keyUsage!: ?KeyUsage = None, extKeyUsage!: ?ExtKeyUsage = None) } +/** + * X509CertificateRequestInfo 结构包含了证书请求信息，包括证书实体可辨识名称、域名、email 地址和 IP 地址。 +*/ public struct X509CertificateRequestInfo { + /** + * 记录证书签名请求的 IP 地址。 + */ public var IPAddresses: Array + + /** + * 记录证书签名请求的 DNS 域名。 + */ public var dnsNames: Array + + /** + * 记录证书签名请求的 email 地址。 + */ public var emailAddresses: Array + + /** + * 记录证书签名请求的实体可辨识名称。 + */ public var subject: ?X509Name + + /** + * 构造 X509CertificateRequestInfo 对象。 + * @param subject!: ?X509Name - 数字证书的使用者信息，默认值为 None。 + * @param dnsNames!: Array - 域名列表，需要用户保证输入域名的有效性，默认值为空的字符串数组。 + * @param emailAddresses!: Array - email 地址列表，需要用户保证输入 email 的有效性，默认值为空的字符串数组。 + * @param IPAddresses!: Array - IP 地址列表，默认值为空的 IP 数组。 + * @throws X509Exception - 输入的 IP 地址列表中包含无效的 IP 地址，则抛出异常。 + */ public init( subject!: ?X509Name = None, dnsNames!: Array = Array(), emailAddresses!: Array = Array(), IPAddresses!: Array = Array()) } @@ -254,6 +1135,9 @@ public struct X509CertificateRequestInfo { // --------------------------- // -----type // --------------------------- -public type IP = Array {} +/** + * x509包用 Array 来记录 IP。 +*/ +public type IP = Array diff --git a/cangjie_libs/encoding/base64.cjd b/cangjie_libs/encoding/base64.cjd index 1bcb709..8ff1361 100644 --- a/cangjie_libs/encoding/base64.cjd +++ b/cangjie_libs/encoding/base64.cjd @@ -3,6 +3,18 @@ package encoding.base64 // --------------------------- // -----funcs // --------------------------- +/** + * 此函数用于 Base64 编码的字符串的解码。 + * @param data: String - 要解码的 Base64 编码的字符串。 + * @return Option> - 输入空字符串会返回 Option>.Some(Array())，解码失败会返回 Option>.None。 +*/ public func fromBase64String(data: String): Option> + +/** + * 此函数用于将 Byte 数组转换成 Base64 编码的字符串。 + * @param data: Array - 要编码的 Byte 数组。 + * @return String - 返回编码后的字符串。 +*/ public func toBase64String(data: Array): String + diff --git a/cangjie_libs/encoding/hex.cjd b/cangjie_libs/encoding/hex.cjd index ce205a8..11d8b1f 100644 --- a/cangjie_libs/encoding/hex.cjd +++ b/cangjie_libs/encoding/hex.cjd @@ -3,6 +3,18 @@ package encoding.hex // --------------------------- // -----funcs // --------------------------- +/** + * 此函数用于 Hex 编码的字符串的解码。 + * @param data: String - 要解码的 Hex 编码的字符串。 + * @return Option> - 输入空字符串会返回 Option>.Some(Array())，解码失败会返回 Option>.None。 +*/ public func fromHexString(data: String): Option> + +/** + * 此函数用于将 Byte 数组转换成 Hex 编码的字符串。 + * @param data: Array - 要编码的 Byte 数组。 + * @return String - 返回编码后的字符串。 +*/ public func toHexString(data: Array): String + diff --git a/cangjie_libs/encoding/json.cjd b/cangjie_libs/encoding/json.cjd index 340e54a..e545ad6 100644 --- a/cangjie_libs/encoding/json.cjd +++ b/cangjie_libs/encoding/json.cjd @@ -3,86 +3,420 @@ package encoding.json // --------------------------- // -----classes // --------------------------- +/** + * 此类为 JsonValue 实现子类，主要用于封装数组类型的 JSON 数据。 + * 示例： + * 使用示例见JsonArray 使用示例。 +*/ public class JsonArray <: JsonValue { + /** + * 创建空 JsonArray。 + */ public init() + + /** + * 将指定的 ArrayList 类型实例封装成 JsonArray 实例。 + * @param list: ArrayList - 用于创建 JsonArray 的 ArrayList。 + */ public init(list: ArrayList) + + /** + * 将指定的 Array 类型实例封装成 JsonArray 实例。 + * @param list: Array - 用于创建 JsonArray 的 Array。 + */ public init(list: Array) + + /** + * 向 JsonArray 中加入 JsonValue 数据。 + * @param jv: JsonValue - 需要加入的 JsonValue。 + * @return JsonArray - 加入数据后的 JsonArray。 + */ public func add(jv: JsonValue): JsonArray + + /** + * 获取 JsonArray 中指定索引的 JsonValue，并用 Option 封装。 + * @param index: Int64 - 指定的索引。 + * @return Option - 对应索引的 JsonValue 数据的封装形式。 + */ public func get(index: Int64): Option + + /** + * 获取 JsonArray 中的 items 数据。 + * @return ArrayList - JsonArray 的 items 数据。 + */ public func getItems(): ArrayList + + /** + * 返回当前 JsonArray 所属的 JsonKind 类型（JsArray）。 + * @return JsonKind - 当前 JsonArray 所属的 JsonKind 类型（JsArray）。 + */ public func kind(): JsonKind + + /** + * 获取 JsonArray 中 JsonValue 的数量。 + * @return Int64 - JsonArray 中 JsonValue 的数量。 + */ public func size(): Int64 + + /** + * 将 JsonArray 转换为 JSON 格式的 (带有空格换行符) 的字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonArray 转换为 JSON 格式的字符串。该函数将指定初始的缩进深度、第一个括号后是否换行以及缩进字符串。 + * @param depth: Int64 - 指定的缩进深度。 + * @param bracketInNewLine!: Bool - 第一个括号是否换行，如果为 true，第一个括号将另起一行并且按照指定的深度缩进。 + * @param indent!: String - 指定的缩进字符串，缩进字符串中只允许空格和制表符的组合，默认为两个空格。 + * @return String - 转换后的 JSON 格式字符串。 + * @throws IllegalArgumentException - 如果 depth 为负数，或 indent 中存在 ' ' 和 '\t' 以外的字符，则抛出异常。 + */ public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false, indent!: String = " "): String + + /** + * 将 JsonString 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String + + /** + * 获取 JsonArray 中指定索引的 JsonValue。 + * @param index: Int64 - 指定的索引。 + * @return JsonValue - 对应索引的 JsonValue。 + * @throws JsonException - 如果 index 不是 JsonArray 的有效索引，抛出异常。 + */ public operator func [](index: Int64): JsonValue } +/** + * 此类为 JsonValue 实现子类，主要用于封装 true 或者 false 的 JSON 数据。 +*/ public class JsonBool <: JsonValue { + /** + * 将指定的 Bool 类型实例封装成 JsonBool 实例。 + */ public init(bv: Bool) + + /** + * 获取 JsonBool 中 value 的实际值。 + * @return Bool - value 的实际值。 + */ public func getValue(): Bool + + /** + * 返回当前 JsonBool 所属的 JsonKind 类型（JsBool）。 + * @return JsonKind - 当前 JsonBool 所属的 JsonKind 类型（JsBool）。 + */ public func kind(): JsonKind + + /** + * 将 JsonBool 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonBool 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String } +/** + * 此类为 JsonValue 实现子类，主要用于封装浮点类型的 JSON 数据。 +*/ public class JsonFloat <: JsonValue { + /** + * 将指定的 Float64 类型实例封装成 JsonFloat 实例。 + * @param fv: Float64 - Float64 类型。 + */ public init(fv: Float64) + + /** + * 将指定的 Int64 类型实例封装成 JsonFloat 实例。 + * @param v: Int64 - Int64 类型。 + */ public init(v: Int64) + + /** + * 获取 JsonFloat 中 value 的实际值。 + * @return Float64 - value 的实际值。 + */ public func getValue(): Float64 + + /** + * 返回当前 JsonFloat 所属的 JsonKind 类型（JsFloat）。 + * @return JsonKind - 当前 JsonFloat 所属的 JsonKind 类型（JsFloat）。 + */ public func kind(): JsonKind + + /** + * 将 JsonFloat 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonFloat 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String } +/** + * 此类为 JsonValue 实现子类，主要用于封装整数类型的 JSON 数据。 +*/ public class JsonInt <: JsonValue { + /** + * 将指定的 Int64 类型实例封装成 JsonInt 实例。 + * @param iv: Int64 - 用于创建 JsonInt 的 Int64。 + */ public init(iv: Int64) + + /** + * 获取 JsonInt 中 value 的实际值。 + * @return Int64 - value 的实际值。 + */ public func getValue(): Int64 + + /** + * 返回当前 JsonInt 所属的 JsonKind 类型（JsInt）。 + * @return JsonKind - 当前 JsonInt 所属的 JsonKind 类型（JsInt）。 + */ public func kind(): JsonKind + + /** + * 将 JsonInt 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonInt 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String } +/** + * 此类为 JsonValue 实现子类，主要用于封装 null 的 JSON 数据。 +*/ public class JsonNull <: JsonValue { + /** + * 返回当前 JsonNull 所属的 JsonKind 类型（JsNull）。 + * @return JsonKind - 当前 JsonNull 所属的 JsonKind 类型（JsNull）。 + */ public func kind(): JsonKind + + /** + * 将 JsonNull 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonNull 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String } +/** + * 此类为 JsonValue 实现子类，主要用于封装 object 类型的 JSON 数据。 +*/ public class JsonObject <: JsonValue { + /** + * 创建空 JsonObject。 + */ public init() + + /** + * 将指定的 HashMap 类型实例封装成 JsonObject 实例。 + */ public init(map: HashMap) + + /** + * 判断 JsonObject 中是否存在 key。 + * @param key: String - 指定的 key。 + * @return Bool - 存在返回 true，不存在返回 false。 + */ public func containsKey(key: String): Bool + + /** + * 获取 JsonObject 中 key 对应的 JsonValue，并用 Option 封装。 + * @param key: String - 指定的 key。 + * @return Option - key 对应的 JsonValue 的封装形式。 + */ public func get(key: String): Option + + /** + * 获取 JsonObject 中的 fields 数据。 + * @return HashMap < String, JsonValue > - JsonObject 的 fields 数据。 + */ public func getFields(): HashMap + + /** + * 返回当前 JsonObject 所属的 JsonKind 类型（JsObject）。 + * @return JsonKind - 当前 JsonObject 所属的 JsonKind 类型（JsObject）。 + */ public func kind(): JsonKind + + /** + * 向 JsonObject 中加入 key-JsonValue 数据。 + * @param key: String - 需要加入的 key。 + * @param v: JsonValue - 对应 key 的 JsonValue。 + */ public func put(key: String, v: JsonValue): Unit + + /** + * 获取 JsonObject 中 fields 存入 string-JsonValue 的数量。 + * @return Int64 - JsonObject 中 fields 的大小。 + */ public func size(): Int64 + + /** + * 将 JsonObject 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonObject 转换为 Json格式的字符串。该函数将指定初始的缩进深度、第一个括号后是否换行以及缩进字符串。 + * @param depth: Int64 - 缩进深度。 + * @param bracketInNewLine!: Bool - 第一个括号是否换行，如果为 true，第一个括号将另起一行并且按照指定的深度缩进。 + * @param indent!: String - 指定的缩进字符串，缩进字符串中只允许空格和制表符的组合，默认为两个空格。 + * @return String - 转换后的 JSON 格式字符串。 + * @throws IllegalArgumentException - 如果 depth 为负数，或 indent 中存在 ' ' 和 '\t' 以外的字符，则抛出异常。 + */ public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false, indent!: String = " "): String + + /** + * 将 JsonObject 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String + + /** + * 获取 JsonObject 中 key 对应的 JsonValue。 + * @param key: String - 指定的 key。 + * @return JsonValue - key 对应的 JsonValue。 + * @throws JsonException - 如果 key 不是 JsonObject 的有效键，抛出异常。 + */ public operator func [](key: String): JsonValue } +/** + * 此类为 JsonValue 实现子类，主要用于封装字符串类型的 JSON 数据。 +*/ public class JsonString <: JsonValue { + /** + * 将指定的 String 类型实例封装成 JsonString 实例。 + */ public init(sv: String) + + /** + * 获取 JsonString 中 value 的实际值。 + * @return String - value 的实际值。 + */ public func getValue(): String + + /** + * 返回当前 JsonString 所属的 JsonKind 类型（JsString）。 + * @return JsonKind - 当前 JsonString 所属的 JsonKind 类型（JsString）。 + */ public func kind(): JsonKind + + /** + * 将 JsonString 转换为 JSON 格式的 (带有空格换行符) 字符串。 + * @return String - 转换后的 JSON 格式字符串。 + */ public func toJsonString(): String + + /** + * 将 JsonString 转换为字符串。 + * @return String - 转换后的字符串。 + */ public func toString(): String } +/** + * 此类为 JSON 数据层，主要用于 JsonValue 和 String 数据之间的互相转换。 + * 抽象类 JsonValue 提供了 String 类型和具体的 JSON 类型相互转换的接口，以及具体的 JSON 类型判断功能。 + * 示例： + * 使用示例见JsonValue 和 String 互相转换。 +*/ sealed abstract class JsonValue <: ToString { + /** + * 将字符串数据解析为 JsonValue。对于整数，支持前导 '0b'，'0o'，'0x'（不区分大小写），分别表示二进制，八进制和十六进制。字符串解析失败时将打印错误字符及其行数和列数，其中列数从错误字符所在行的非空格字符起开始计算。 + * JSON 在解析 String 转换为 JsonValue 时，转义字符 \ 之后只能对应 JSON 支持的转义字符（b、f、n、r、t、u、\、"、/），其中 \u 的格式为：\uXXXX，X 为十六进制数，例：\u0041 代表字符 'A'。 + * 示例： + * @param s: String - 传入字符串，暂不支持 "?" 和特殊字符。 + * @return JsonValue - 转换后的 JsonValue。 + * @throws JsonException - 如果内存分配失败，或解析字符串出错，抛出异常。 + */ public static func fromStr(s: String): JsonValue + + /** + * 运行结果如下： + */ public func asArray(): JsonArray + public func asBool(): JsonBool + + /** + * 将 JsonValue 转换为 JsonArray 格式。 + * @return JsonArray - 转换后的 JsonArray。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func asFloat(): JsonFloat + + /** + * 将 JsonValue 转换为 JsonBool 格式。 + * @return JsonBool - 转换后的 JsonBool。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func asInt(): JsonInt + + /** + * 将 JsonValue 转换为 JsonFloat 格式。 + * @return JsonFloat - 转换后的 JsonFloat。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func asNull(): JsonNull + + /** + * 将 JsonValue 转换为 JsonInt 格式。 + * @return JsonInt - 转换后的 JsonInt。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func asObject(): JsonObject + + /** + * 将 JsonValue 转换为 JsonNull 格式。 + * @return JsonNull - 转换后的 JsonNull。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func asString(): JsonString + + /** + * 将 JsonValue 转换为 JsonObject 格式。 + * @return JsonObject - 转换后的 JsonObject。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func kind(): JsonKind + + /** + * 将 JsonValue 转换为 JsonString 格式。 + * @return JsonString - 转换后的 JsonString。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func toJsonString(): String + + /** + * 返回当前 JsonValue 所属的 JsonKind 类型。 + * @return JsonKind - 当前 JsonValue 所属的 JsonKind 类型。 + */ public func toString(): String } @@ -90,22 +424,63 @@ sealed abstract class JsonValue <: ToString { // --------------------------- // -----enums // --------------------------- +/** + * 表示 JsonValue 的具体类型。 +*/ public enum JsonKind { - JsArray - JsBool - JsFloat - JsInt - JsNull - JsObject - JsString + /** + * 表示 JSON 类型中的数组类型。 + */ + | JsArray + + /** + * 表示 true 或者 false 类型。 + */ + | JsBool + + /** + * 表示值为浮点数的 number 类型。 + */ + | JsFloat + + /** + * 表示值为整数的 number 类型。 + */ + | JsInt + + /** + * 表示 null 类型。 + */ + | JsNull + + /** + * 表述 JSON 类型中的对象类型。 + */ + | JsObject + + /** + * 表示 string 类型。 + */ + | JsString } // --------------------------- // -----exceptions // --------------------------- +/** + * JSON 包的异常类，用于 JsonValue 类型使用时出现异常的场景。 +*/ public class JsonException <: Exception { + /** + * 构造一个不包含任何异常提示信息的 JsonException 实例。 + */ public init() + + /** + * 根据指定的异常提示信息构造 JsonException 实例。 + * @param message: String - 指定的异常提示信息。 + */ public init(message: String) } @@ -113,13 +488,41 @@ public class JsonException <: Exception { // --------------------------- // -----interfaces // --------------------------- +/** + * 用于实现 JsonValue 和 DataModel 的相互转换。 +*/ public interface ToJson { + /** + * 将 JsonValue 转化为对象 DataModel。 + * @param jv: JsonValue - 待转换的 JsonValue。 + * @return DataModel - 转换后的 DataModel。 + */ static func fromJson(jv: JsonValue): DataModel + + /** + * 将自身转化为 JsonValue。 + * @return JsonValue - 转换后的 JsonValue。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ func toJson(): JsonValue } +/** + * 为 DataModel 类型实现 ToJson 接口。 +*/ extend DataModel <: ToJson { + /** + * 将 JsonValue 转化为对象 DataModel。 + * @param jv: JsonValue - 待转换的 JsonValue。 + * @return DataModel - 转换后的 DataModel。 + */ public static func fromJson(jv: JsonValue): DataModel + + /** + * 将自身转化为 JsonValue。 + * @return JsonValue - 转换后的 JsonValue。 + * @throws JsonException - 如果转换失败，抛出异常。 + */ public func toJson(): JsonValue } diff --git a/cangjie_libs/encoding/json.stream.cjd b/cangjie_libs/encoding/json.stream.cjd index f0443cd..f2824cf 100644 --- a/cangjie_libs/encoding/json.stream.cjd +++ b/cangjie_libs/encoding/json.stream.cjd @@ -3,29 +3,145 @@ package encoding.json.stream // --------------------------- // -----classes // --------------------------- +/** + * 此类提供 JSON 数据流转仓颉对象的反序列化能力。 + * 示例： + * 使用示例见使用 Json Stream 进行反序列化 +*/ public class JsonReader { + /** + * 根据输入流创建一个 JsonReader， JsonReader 从输入流中读取数据时，将跳过非 JsonString 中的空字符（'\0', '\t', '\n', '\r'）。 + * @param inputStream: InputStream - 输入的 JSON 数据流。 + */ public init(inputStream: InputStream) + + /** + * 从输入流的当前位置跳过空白字符后消耗一个 ']' 字符，endArray 必须有一个 startArray 与之对应。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func endArray(): Unit + + /** + * 从输入流的当前位置跳过空白字符后消耗一个 '}' 字符，endObject 必须有一个 startObject 与之对应。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func endObject(): Unit + + /** + * 获取输入流的下一个 JsonToken 的类型，不保证下一个 JsonToken 的格式一定正确。 + * 例：如果输入流中的下一个字符为 't'，获取的 JsonToken 将为 JsonToken.Bool，但调用 readValue() 不一定成功。 + * @return Option - 获取到的下一个 JsonToken 的类型，如果到了输入流的结尾返回 None。 + * @throws IllegalStateException - 如果输入流的下一个字符不在以下范围内：(n, t, f, ", 0~9, -, {, }, [, ])。 + */ public func peek(): Option + + /** + * 从输入流的当前位置读取一个 name。 + * @return String - 读取出的 name 值。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func readName(): String + + /** + * 从输入流的当前位置读取一个 value。 + * @return T - 读取出的 value 值。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func readValue(): T where T <: JsonDeserializable + + /** + * 从输入流的当前位置跳过一组数据。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func skip(): Unit + + /** + * 从输入流的当前位置跳过空白字符后消耗一个 '[' 字符。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func startArray(): Unit + + /** + * 从输入流的当前位置跳过空白字符后消耗一个 '{' 字符。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ public func startObject(): Unit } +/** + * JsonWriter 提供了将仓颉对象序列化到 OutputStream 的能力。 + * JsonWriter 需要和 interface JsonSerializable 搭配使用，JsonWriter 可以通过 writeValue 来将实现了 JsonSerializable 接口的类型写入到 Stream 中。 + * 示例： + * 使用示例见使用 Json Stream 进行序列化 +*/ public class JsonWriter { + /** + * 构造函数，构造一个将数据写入 out 的实例。 + * @param out: OutputStream - 目标流 + */ public init(out: OutputStream) + + /** + * 序列化格式配置。详见 WriteConfig。 + */ public var writeConfig = WriteConfig.compact + + /** + * 结束序列化当前的 JSON 数组。 + * @throws IllegalStateException - 当前 writer 没有匹配的 startArray 时。 + */ public func endArray(): Unit + + /** + * 结束序列化当前的 JSON object。 + * @throws IllegalStateException - 当前 writer 的状态不应该结束一个 JSON object 时。 + */ public func endObject(): Unit + + /** + * 将缓存中的数据写入 out，并且调用 out 的 flush 方法。 + */ public func flush(): Unit + + /** + * 将符合JSON value规范的原始字符串写入stream。 + * @return JsonWriter - 为方便链式调用，返回值为当前 JsonWriter 的引用。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func jsonValue(value: String): JsonWriter + + /** + * 开始序列化一个新的 JSON 数组，每一个 startArray 都必须有一个 endArray 对应。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 JSON array 时。 + */ public func startArray(): Unit + + /** + * 开始序列化一个新的 JSON object，每一个 startObject 都必须有一个 endObject 对应。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 JSON object 时。 + */ public func startObject(): Unit + + /** + * 在 object 结构中写入 name。 + * @return JsonWriter - 当前 JsonWriter 引用。 + * @throws IllegalStateException - 当前 JsonWriter 的状态不应写入参数 name 指定字符串时。 + */ public func writeName(name: String): JsonWriter + + /** + * 向流中写入 JSON value null。 + * @return JsonWriter - 为方便链式调用，返回值为当前 JsonWriter 的引用。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时 + */ public func writeNullValue(): JsonWriter + + /** + * 将实现了 JsonSerializable 接口的类型写入到 Stream 中。该接口会调用泛型 T 的 toJson 方法向输出流中写入数据。 + * json.stream 包已经为基础类型 Int64、UInt64、Float64、Bool、String类型扩展实现了 JsonSerializable， 并且为 Collection 类型 Array、ArrayList和 HashMap 扩展实现了 JsonSerializable。 + * @return JsonWriter - 返回当前 JsonWriter 的引用。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeValue(v: T): JsonWriter where T <: JsonSerializable } @@ -33,18 +149,74 @@ public class JsonWriter { // --------------------------- // -----enums // --------------------------- +/** + * 表示 JSON 编码的字符串中的结构、名称或者值类型。 + * JsonToken 通常和 JsonReader.peek()搭配使用，通过对返回值的判断来决定具体的处理方式。 +*/ public enum JsonToken <: Equatable & Hashable { - BeginArray - BeginObject - EndArray - EndObject - JsonBool - JsonNull - JsonNumber - JsonString - Name + /** + * 表示 JSON 中 array 的开始。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.startArray() 读取。 + */ + | BeginArray + + /** + * 表示 JSON 中 object 的开始。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.startObject() 读取。 + */ + | BeginObject + + /** + * 表示 JSON 中 array 的结束。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.endArray() 读取。 + */ + | EndArray + + /** + * 表示 JSON 中 object 的结束。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.endObject() 读取。 + */ + | EndObject + + /** + * 表示 JSON 的 bool 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。 + */ + | JsonBool + + /** + * 表示 JSON 的 null 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue>() 读取。 + */ + | JsonNull + + /** + * 表示 JSON 的 number 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。 + */ + | JsonNumber + + /** + * 表示 JSON 的 string 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。 + */ + | JsonString + + /** + * 表示 object 中的 name。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readName() 读取。 + */ + | Name + + /** + * 获取 JsonToken 对象的 hashCode 值。 + * @return Int64 - hashCode 值。 + */ public func hashCode(): Int64 + + /** + * 判不等。 + * @param that: JsonToken - 被比较的 JsonToken 对象 + * @return Bool - 当前实例与 that 不相等返回 true，否则返回 false + */ public operator func !=(that: JsonToken): Bool + + /** + * 判等。 + * @param that: JsonToken - 被比较的 JsonToken 对象 + * @return Bool - 当前实例与 that 相等返回 true，否则返回 false + */ public operator func ==(that: JsonToken): Bool } @@ -52,187 +224,539 @@ public enum JsonToken <: Equatable & Hashable { // --------------------------- // -----interfaces // --------------------------- +/** + * 此接口用于实现从 JsonReader 中读取一个仓颉对象。 + * 支持的对象类型包括： +*/ public interface JsonDeserializable { + /** + * 从参数 r 指定的 JsonReader 实例中读取一个 T 类型对象。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return T - T 类型的实例。 + * @throws IllegalStateException - 如果输入流的 JSON 数据不符合格式，抛出异常。 + */ static func fromJson(r: JsonReader): T } +/** + * 为 BigInt 类型实现 JsonDeserializable 接口。 +*/ extend BigInt <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 BigInt。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return BigInt - BigInt 类型的实例。 + */ public static func fromJson(r: JsonReader): BigInt } +/** + * 为 Bool 类型实现 JsonDeserializable 接口。 +*/ extend Bool <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Bool。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Bool - Bool 类型的实例。 + */ public static func fromJson(r: JsonReader): Bool } +/** + * 为 DateTime 类型实现 JsonDeserializable 接口。 +*/ extend DateTime <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 DateTime 实例。 + * 该函数将会把读取到的字符串按照 RFC3339 的规范解析，可包含小数秒格式，函数的行为参考DateTime的func parse(String)。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return DateTime - DateTime 类型的实例。 + * @throws TimeParseException - 无法正常解析时，抛出异常。 + */ public static func fromJson(r: JsonReader): DateTime } +/** + * 为 Decimal 类型实现 JsonDeserializable 接口。 +*/ extend Decimal <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Decimal。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Decimal - Decimal 类型的实例。 + */ public static func fromJson(r: JsonReader): Decimal } +/** + * 为 Float16 类型实现 JsonDeserializable 接口。 +*/ extend Float16 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Float16。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Float16 - Float16 类型的实例。 + */ public static func fromJson(r: JsonReader): Float16 } +/** + * 为 Float32 类型实现 JsonDeserializable 接口。 +*/ extend Float32 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Float32。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Float32 - Float32 类型的实例。 + */ public static func fromJson(r: JsonReader): Float32 } +/** + * 为 Float64 类型实现 JsonDeserializable 接口。 +*/ extend Float64 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Float64。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Float64 - Float64 类型的实例。 + */ public static func fromJson(r: JsonReader): Float64 } +/** + * 为 String 类型实现 JsonDeserializable 接口。 +*/ extend String <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 String。 + * 根据下一个 JsonToken 的不同，String 的反序列化结果将会不同： + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return String - String 类型的实例。 + */ public static func fromJson(r: JsonReader): String } +/** + * 为 Int16 类型实现 JsonDeserializable 接口。 +*/ extend Int16 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Int16。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Int16 - Int16 类型的实例。 + */ public static func fromJson(r: JsonReader): Int16 } +/** + * 为 Int32 类型实现 JsonDeserializable 接口。 +*/ extend Int32 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Int32。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Int32 - Int32 类型的实例。 + */ public static func fromJson(r: JsonReader): Int32 } +/** + * 为 Int64 类型实现 JsonDeserializable 接口。 +*/ extend Int64 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Int64。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Int64 - Int64 类型的实例。 + */ public static func fromJson(r: JsonReader): Int64 } +/** + * 为 Int8 类型实现 JsonDeserializable 接口。 +*/ extend Int8 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Int8。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Int8 - Int8 类型的实例。 + */ public static func fromJson(r: JsonReader): Int8 } +/** + * 为 IntNative 类型实现 JsonDeserializable 接口。 +*/ extend IntNative <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 IntNative。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return IntNative - IntNative 类型的实例。 + */ public static func fromJson(r: JsonReader): IntNative } +/** + * 为 UInt16 类型实现 JsonDeserializable 接口。 +*/ extend UInt16 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 UInt16。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return UInt16 - UInt16 类型的实例。 + */ public static func fromJson(r: JsonReader): UInt16 } +/** + * 为 UInt32 类型实现 JsonDeserializable 接口。 +*/ extend UInt32 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 UInt32。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return UInt32 - UInt32 类型的实例。 + */ public static func fromJson(r: JsonReader): UInt32 } +/** + * 为 UInt64 类型实现 JsonDeserializable 接口。 +*/ extend UInt64 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 UInt64。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return UInt64 - UInt64 类型的实例。 + */ public static func fromJson(r: JsonReader): UInt64 } +/** + * 为 UInt8 类型实现 JsonDeserializable 接口。 +*/ extend UInt8 <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 UInt8。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return UInt8 - UInt8 类型的实例。 + */ public static func fromJson(r: JsonReader): UInt8 } +/** + * 为 UIntNative 类型实现 JsonDeserializable 接口。 +*/ extend UIntNative <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 UIntNative。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return UIntNative - UIntNative 类型的实例。 + */ public static func fromJson(r: JsonReader): UIntNative } +/** + * 为 Array 类型实现 JsonDeserializable 接口。 +*/ extend Array <: JsonDeserializable> where T <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 Array。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Array - Array 类型的实例。 + */ public static func fromJson(r: JsonReader): Array } +/** + * 为 ArrayList 类型实现 JsonDeserializable 接口。 +*/ extend ArrayList <: JsonDeserializable> where T <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个 ArrayList。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return ArrayList - ArrayList 类型的实例。 + */ public static func fromJson(r: JsonReader): ArrayList } +/** + * 为 Option 类型实现 JsonDeserializable 接口。 +*/ extend Option <: JsonDeserializable> where T <: JsonDeserializable { + /** + * 从 JsonReader 中读取一个Option。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return Option - Option 类型的实例。 + */ public static func fromJson(r: JsonReader): Option } +/** + * 为 HashMap 类型实现 JsonDeserializable 接口。 +*/ extend HashMap <: JsonDeserializable> where V <: JsonDeserializable, K <: String { + /** + * 从 JsonReader 中读取一个 HashMap。 + * @param r: JsonReader - 读取反序列化结果的 JsonReader 实例。 + * @return HashMap - HashMap 类型的实例。 + */ public static func fromJson(r: JsonReader): HashMap } +/** + * 为类型提供序列化到 JSON 数据流的接口。 + * 与 JsonWriter 搭配使用，JsonWriter 可以将实现了 JsonSerializable 接口的类型写入到 Stream 中。 +*/ public interface JsonSerializable { + /** + * 将实现了 JsonSerializable 接口的类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ func toJson(w: JsonWriter): Unit } +/** + * 为BigInt类型提供序列化到 JSON 数据流的接口。 +*/ extend BigInt <: JsonSerializable { + /** + * 将BigInt类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Bool类型提供序列化到 JSON 数据流的接口。 +*/ extend Bool <: JsonSerializable { + /** + * 将Bool类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为 DateTime 类型实现 JsonSerializable 接口。 +*/ extend DateTime <: JsonSerializable { + /** + * 提供 DateTime 类型序列化到流的功能。 + * 该接口的功能与 JsonWriter 的 writeConfig中的属性 dateTimeFormat有关联，将会把 DateTime 按照dateTimeFormat中的格式输出到目标流中，可以通过修改dateTimeFormat实现不同的格式控制。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Decimal类型提供序列化到 JSON 数据流的接口。 +*/ extend Decimal <: JsonSerializable { + /** + * 将Decimal类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Float16类型提供序列化到 JSON 数据流的接口。 +*/ extend Float16 <: JsonSerializable { + /** + * 将Float16类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Float32类型提供序列化到 JSON 数据流的接口。 +*/ extend Float32 <: JsonSerializable { + /** + * 将Float32类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Float64类型提供序列化到 JSON 数据流的接口。 +*/ extend Float64 <: JsonSerializable { + /** + * 将Float64类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为String类型提供序列化到 JSON 数据流的接口。 +*/ extend String <: JsonSerializable { + /** + * 将String类型写入参数 w 指定的 JsonWriter 实例中。写入的String + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Int16类型提供序列化到 JSON 数据流的接口。 +*/ extend Int16 <: JsonSerializable { + /** + * 将Int16类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Int32类型提供序列化到 JSON 数据流的接口。 +*/ extend Int32 <: JsonSerializable { + /** + * 将Int32类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Int64类型提供序列化到 JSON 数据流的接口。 +*/ extend Int64 <: JsonSerializable { + /** + * 将Int64类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Int8类型提供序列化到 JSON 数据流的接口。 +*/ extend Int8 <: JsonSerializable { + /** + * 将Int8类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为IntNative类型提供序列化到 JSON 数据流的接口。 +*/ extend IntNative <: JsonSerializable { + /** + * 将IntNative类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为UInt16类型提供序列化到 JSON 数据流的接口。 +*/ extend UInt16 <: JsonSerializable { + /** + * 将UInt16类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为UInt32类型提供序列化到 JSON 数据流的接口。 +*/ extend UInt32 <: JsonSerializable { + /** + * 将UInt32类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为UInt64类型提供序列化到 JSON 数据流的接口。 +*/ extend UInt64 <: JsonSerializable { + /** + * 将UInt64类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为UInt8类型提供序列化到 JSON 数据流的接口。 +*/ extend UInt8 <: JsonSerializable { + /** + * 将UInt8类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为UIntNative类型提供序列化到 JSON 数据流的接口。 +*/ extend UIntNative <: JsonSerializable { + /** + * 将UIntNative类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Array类型提供序列化到 JSON 数据流的接口。 +*/ extend Array <: JsonSerializable where T <: JsonSerializable { + /** + * 将Array类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为ArrayList类型提供序列化到 JSON 数据流的接口。 +*/ extend ArrayList <: JsonSerializable where T <: JsonSerializable { + /** + * 将ArrayList类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为Option类型提供序列化到 JSON 数据流的接口。 +*/ extend Option <: JsonSerializable where T <: JsonSerializable { + /** + * 将Option类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } +/** + * 为HashMap类型提供序列化到 JSON 数据流的接口。 +*/ extend HashMap <: JsonSerializable where V <: JsonSerializable, K <: String { + /** + * 将HashMap类型写入参数 w 指定的 JsonWriter 实例中。 + * @param w: JsonWriter - 写入序列化结果的 JsonWriter 实例。 + */ public func toJson(w: JsonWriter): Unit } @@ -240,13 +764,45 @@ extend HashMap <: JsonSerializable where V <: JsonSerializable, K <: // --------------------------- // -----structs // --------------------------- +/** + * 用于表示 JsonWriter 的序列化格式配置。 + * 示例： + * 使用示例见 WriteConfig 使用示例。 +*/ public struct WriteConfig { + /** + * 提供紧凑的序列化格式。 + * 示例： + */ public static let compact: WriteConfig + public static let pretty: WriteConfig + + /** + * 提供整洁的序列化格式。 + * 示例： + */ public mut prop dateTimeFormat: DateTimeFormat + public mut prop htmlSafe: Bool + + /** + * 用于序列化 DateTime 类型时的格式控制，功能与 DateTime 的 func toString(DateTimeFormat)一致。 + */ public mut prop indent: String + + /** + * 用于表示是否转义 HTML 字符 <、>、&、=和'。 + * 该值为 true 时，会将 HTML 字符转义为对应的 Unicode 编码的字符串。 + * 该选项只对 json value 中的字符串字面量有效。 + */ public mut prop newline: String + + /** + * 用于表示序列化时每个缩进级别填入的缩进字符串。取值应匹配正则 ^[ \t]*$。 + * 当上述的换行起作用时，该值会作为换行后的填充符。 + * @throws IllegalArgumentException - 设置的字符串包含 ' ' 或者 '\t' 以外的字符。 + */ public mut prop useSpaceAfterSeparators: Bool } diff --git a/cangjie_libs/encoding/url.cjd b/cangjie_libs/encoding/url.cjd index fe67ab2..4b6d2b9 100644 --- a/cangjie_libs/encoding/url.cjd +++ b/cangjie_libs/encoding/url.cjd @@ -3,50 +3,263 @@ package encoding.url // --------------------------- // -----classes // --------------------------- +/** + * Form 以 key-value 键值对形式存储 http 请求的表单信息，通常为请求 URL 中的 query 部分。 + * 同一个 key 可以对应多个 value，value 以数组形式存储。& 符号分隔多个键值对；= 分隔的左侧作为 key 值，右侧作为 value 值（没有 = 或者 value 为空，均是允许的）。 +*/ public class Form { + /** + * 构造一个默认的 Form 实例。 + */ public init() + + /** + * 根据 URL 编码的查询字符串，即 URL 实例的 query 部分构造 Form 实例。 + * 解析 URL 编码的查询字符串，得到若干键值对，并将其添加到新构造的 Form 实例中。 + * @param queryComponent: String - URL 的 query 组件部分的字符串，但是不包括组件前面的 ? 符号。 + * @throws IllegalArgumentException - 当URL 字符串中包含不符合 utf8 编码规则的字节时，抛出异常。 + */ public init(queryComponent: String) + + /** + * 新增 key-value 映射，如果 key 已存在，则将 value 添加到原来 value 数组的最后面。 + * @param key: String - 指定键，可以是新增的。 + * @param value: String - 将该值添加到指定键对应的值数组中。 + */ public func add(key: String, value: String): Unit + + /** + * 克隆 Form。 + * @return Form - 克隆得到的新 Form 实例。 + */ public func clone(): Form + + /** + * 根据 key 获取第一个对应的 value 值。 + * 举例： + * @param key: String - 指定键。 + * @return Option - 根据指定键获取的第一个值，用 Option 类型表示。 + */ public func get(key: String): Option + + /** + * 根据指定的键（key）获取该键（key）对应的所有 value 值。 + * @param key: String - 用户指定的键（key），用于获取对应的 value 值。 + * @return ArrayList - 根据指定键（key）获取的全部 value 值对应的数组。当指定键（key）不存在时，返回空数组。 + */ public func getAll(key: String): ArrayList + + /** + * 判断 Form 是否为空。 + * @return Bool - 如果为空，则返回 true；否则，返回 false。 + */ public func isEmpty(): Bool + + /** + * 删除 key 及其对应 value。 + * @param key: String - 需要删除的键。 + */ public func remove(key: String): Unit + + /** + * 重置指定 key 对应的 value。 + * @param key: String - 指定键。 + * @param value: String - 将指定键的值设置为 value。 + */ public func set(key: String, value: String): Unit + + /** + * 对表单中的键值对进行编码，编码采用百分号编码。 + * 未保留字符不会被编码，空格将编码为 '+'。 + * @return String - 编码后的字符串。 + */ public func toEncodeString(): String } +/** + * 该类提供解析 URL 的函数以及其他相关函数。 + * 字符串中被百分号%编码的内容会被解码，保存在相应的组件之中，而初始值保存在相应的 raw 属性之中。URL 中的用户名和密码部分（如果存在的话）也会按照 RFC 3986 协议的说明被解析。 +*/ public class URL <: ToString { + /** + * 获取解码后的锚点组件，用字符串表示。 + */ public prop fragment: ?String + + /** + * 获取解码后的主机名和端口部分，用字符串表示。 + */ public prop host: String + + /** + * 获取解码后的主机名，用字符串表示。 + */ public prop hostName: String + + /** + * 获取 URL 中不透明部分，用字符串表示。 + */ public prop opaque: String + + /** + * 获取解码后的路径，用字符串表示。 + */ public prop path: String + + /** + * 获取端口号，用字符串表示，空字符串表示无端口号。 + */ public prop port: String + + /** + * 获取解码后的查询组件，用字符串表示。 + */ public prop query: ?String + + /** + * 获取解码后的查询组件，用 Form 实例表示。 + */ public prop queryForm: Form + + /** + * 获取解码前的锚点组件，用字符串表示。 + */ public prop rawFragment: ?String + + /** + * 获取解码前的路径，用字符串表示。 + */ public prop rawPath: String + + /** + * 获取解码前的查询组件，用字符串表示。 + */ public prop rawQuery: ?String + + /** + * 获取解码前的用户名和密码信息，用 UserInfo 实例表示。 + */ public prop rawUserInfo: UserInfo + + /** + * 获取 URL 中协议部分，用字符串表示。 + */ public prop scheme: String + + /** + * 获取解码后的用户名和密码信息，用 UserInfo 实例表示。 + */ public prop userInfo: UserInfo + + /** + * 构造一个 URL 实例。 + * 构造实例时需要满足要求： + * @param scheme!: String - 协议类型。 + * @param hostName!: String - 不包含端口号的主机名。 + * @param path!: String - 请求资源的路径。 + * @throws UrlSyntaxException - 当构造实例不满足要求时，抛出异常。 + */ public init(scheme!: String, hostName!: String, path!: String) + + /** + * 合并两个路径。 + * 合并规则：将引用路径 refPath 追加到基础路径 basePath 的最后一段。如果 refPath 是绝对路径，结果就是 refPath 原本的值。如果 refPath 不是绝对路径，则将自身拼接至 basePath 最后一个 / 后，所有结果最终都会进行标准化（路径中的.字符，..字符，以及多个连续的 / 字符都会被优化）。具体行为可以参照下面示例。更详细行为参考 RFC 3986 协议。 + * 例如： + * @param basePath: String - 基础路径。 + * @param refPath: String - 引用路径。 + * @return String - 合并且标准化后的路径。 + */ public static func mergePaths(basePath: String, refPath: String): String + + /** + * 将原始 URL 字符串解析成 URL 对象。 + * 这个函数会将 URL 按照组件分解，然后分别进行解码并存储在相应的组件属性中，而 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性部分存储的是原始值，不做编解码处理。 + * 使用示例请参见URL 解析函数 parse 的使用。 + * @param rawUrl: String - URL 字符串。 + * @return URL - 解析字符串得到的 URL 实例。 + * @throws UrlSyntaxException - 当 URL 字符串中包含非法字符时，抛出异常。 + */ public static func parse(rawUrl: String): URL + + /** + * 判断 URL 是否为绝对 URL（scheme 存在时，URL 是绝对 URL）。 + * @return Bool - scheme 存在时返回 true，不存在时返回 false。 + */ public func isAbsoluteURL(): Bool + + /** + * 替换 URL 对象的各组件，并且返回一个新的 URL 对象。 + * 替换时需要满足以下要求： + * @param scheme!: Option - 协议组件。 + * @param userInfo!: Option - 用户信息。 + * @param hostName!: Option - 主机名。 + * @param port!: Option - 端口号。 + * @param path!: Option - 资源路径。 + * @param query!: Option - 查询组件。 + * @param fragment!: Option - 锚点组件。 + * @return URL - 新的 URL 对象。 + * @throws UrlSyntaxException - 不满足替换要求时，抛出异常。 + */ public func replace(scheme!: Option = None, userInfo!: Option = None, hostName!: Option = None, port!: Option = None, path!: Option = None, query!: Option = None, fragment!: Option = None): URL + + /** + * 以当前 URL 实例为基础 URL，以传入的 URL 为参考 URL，根据 RFC 3986 协议生成一个新的 URL 实例。 + * 例如：http://a/b/c/d;p?q 为基础 URL，以下 = 左边为参考 URL，右边为生成的新 URL： + * 更多详细的 URL 生成规则，请参见 RFC 3968 协议。 + * @param ref: URL - 参考 URL 对象。 + * @return URL - 新的 URL 实例。 + */ public func resolveURL(ref: URL): URL + + /** + * 获取当前 URL 实例的字符串值。 + * 会把 hostName 编码，其余部分取 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性值，按照 URL 组件构成顺序进行拼接而获得该函数返回值。 + * @return String - 当前 URL 实例的字符串值。 + */ public func toString(): String } +/** + * UserInfo 表示 URL 中用户名和密码信息。 +*/ public class UserInfo <: ToString { + /** + * 创建 UserInfo 实例。 + */ public init() + + /** + * 根据用户名创建 UserInfo 实例。 + * @param userName: String - 用户名。 + */ public init(userName: String) + + /** + * 根据用户名和密码创建 UserInfo 实例。 参数： + */ public init(userName: String, passWord: Option) + + /** + * 根据用户名和密码创建 UserInfo 实例。 参数： + */ public init(userName: String, passWord: String) + + /** + * 获取密码信息。 + * @return Option - 将密码以 Option 形式返回。 + */ public func password(): Option + + /** + * 将当前 UserInfo 实例转换为字符串。 + * @return String - 当前 UserInfo 实例的字符串表示。 + */ public func toString(): String + + /** + * 获取用户名信息。 + * @return String - 字符串类型的用户名。 + */ public func username(): String } @@ -54,9 +267,29 @@ public class UserInfo <: ToString { // --------------------------- // -----exceptions // --------------------------- +/** + * URL 解析异常类。 +*/ public class UrlSyntaxException <: Exception { + /** + * 根据错误原因构造 UrlSyntaxException 实例。 + * @param reason: String - 解析错误的原因。 + */ public init(reason: String) + + /** + * 根据 URL 及错误原因构造 UrlSyntaxException 实例。 + * @param input: String - 原生 URL 或其片段。 + * @param reason: String - 解析错误的原因。 + */ public init(input: String, reason: String) + + /** + * 根据 URL 字符串，错误原因以及解析失败的部分，构造 UrlSyntaxException 实例。 + * @param input: String - 原生 URL 或其片段。 + * @param reason: String - 解析错误的原因。 + * @param pos: String - 给定 URL 字符串中解析失败的部分。 + */ public init(input: String, reason: String, pos: String) } diff --git a/cangjie_libs/encoding/xml.cjd b/cangjie_libs/encoding/xml.cjd index 1fcc2fa..332f15d 100644 --- a/cangjie_libs/encoding/xml.cjd +++ b/cangjie_libs/encoding/xml.cjd @@ -3,29 +3,125 @@ package encoding.xml // --------------------------- // -----classes // --------------------------- +/** + * 此类存储 XML 元素节点属性，并提供查询其内容的函数。 + * 部分接口提供了有限的检查功能，例如节点名称为空，首字母为 '-' 、 '.' 、 '[0-9]' 等。 +*/ public class XmlAttr <: ToString { + /** + * 获取或设置属性值。 + */ public mut prop content: String + + /** + * 获取或设置属性名称。 + * @throws XmlException - 当属性名称为空，或首字母为 '-' 、 '.' 、 '[0-9]' 时，抛出异常。 + */ public mut prop name: String + + /** + * 创建一个 XmlAttr 对象。 + * @param name: String - 属性名称。 + * @param content: String - 属性值。 + * @throws XmlException - 当属性名称为空，或首字母为 '-' 、 '.' 、 '[0-9]' 时，抛出异常。 + */ public init(name: String, content: String) + + /** + * 将 XmlAttr 转换成字符串。 + * @return String - 当前 XmlAttr 实例的字符串值。 + */ public func toString(): String } +/** + * 此类存储 XML 元素节点，并提供查询其内容的函数。 + * 部分接口提供了有限的检查功能，例如节点名称为空，首字母为 '-' 、 '.' 、 '[0-9]'，属性名称必须保证唯一等。 +*/ public class XmlElement <: ToString { + /** + * 获取节点的属性，返回节点属性的深拷贝，设置节点的属性。 + * @throws XmlException - 当设置节点属性时，如果传入的属性列表中有重复字段，抛出异常。 + */ public mut prop attributes: ArrayList + + /** + * 获取节点的属性个数。 + */ public prop attributesNum: Int64 + + /** + * 获取或设置节点的所有子节点。 + */ public mut prop childrenElements: ArrayList + + /** + * 获取节点的子节点个数。 + */ public prop childrenNum: Int64 + + /** + * 获取或设置节点文本内容。 + */ public mut prop content: String + + /** + * 判断节点是否闭合。 + */ public prop isClosed: Bool + + /** + * 获取或设置节点名称。 + * @throws XmlException - 当设置节点名称为空，或首字母为 '-' 、 '.' 、 '[0-9]' 时，抛出异常。 + */ public mut prop name: String + + /** + * 创建一个 XmlElement 对象。 + * @param name: String - 节点名称。 + * @param content: String - 节点文本内容。 + * @throws XmlException - 当设置节点名称为空，或首字母为 '-' 、 '.' 、 '[0-9]' 时，抛出异常。 + */ public init(name: String, content: String) + + /** + * 返回 XML 字符串，该字符串会在一行显示，其中的实体引用将会被解析，例如: '<' 将替换成 '<'。 + * @return String - 解析得到的字符串。 + */ public func toString(): String + + /** + * 返回格式化后的 XML 字符串，该字符串会以 XML 的格式体现，其中的实体引用将会被解析，例如: '<' 将替换成 '<'。 + * @return String - 解析并且格式化后的字符串。 + */ public func toXmlString(): String } +/** + * 此类提供 XML 解析功能。 + * 目前支持两种模式：文档对象模型（DOM）模式和 XML 简单 API（SAX）模式，暂不支持外部实体功能，以及 形式的指令声明。 + * 支持 5 个内置符号的解析，如下表所示： | 符号 | 字符 | | --- | --- | | < | <, <, < | | > | >, >, > | | & | &, &, & | | ' | ', ', ' | | " | ", ", " | +*/ public class XmlParser { + /** + * 创建 XML 文档对象模型（DOM）模式解析器。 + * @throws XmlException - 当初始化失败时，抛出异常。 + */ public init() + + /** + * 创建 XML 简单 API（SAX）模式解析器。 + * @param handler: SaxHandler - 实现了 SaxHandler 的一组回调函数。 + * @throws XmlException - 当初始化失败时，抛出异常。 + */ public init(handler: SaxHandler) + + /** + * 解析字符串类型的 XML 文本。 + * @param str: String - XML 文本，最大解析长度 2^32 - 1, 即 UInt32 的最大值。 + * @return Option - DOM 模式下如果解析成功则返回 Option.Some(element)，失败则返回 Option.None；SAX 模式下返回 Option.None。 + * @throws XmlException - 当内存分配失败，或解析文本出错，或存在空指针时，抛出异常。 + */ public func parse(str: String): Option } @@ -33,8 +129,19 @@ public class XmlParser { // --------------------------- // -----exceptions // --------------------------- +/** + * XML异常类，XML处理错误时抛出的异常。 +*/ public class XmlException <: Exception { + /** + * 创建 XmlException 实例。 + */ public init() + + /** + * 根据异常信息创建 XmlException 实例。 + * @param message: String - 异常信息提示字符串。 + */ public init(message: String) } @@ -42,11 +149,38 @@ public class XmlException <: Exception { // --------------------------- // -----interfaces // --------------------------- +/** + * 提供 XML 简单 API（SAX）模式的回调函数接口。 + * SAX（Simple API for XML）是一种基于流的解析方式，边读取 XML 边解析，并以事件回调的方式让调用者获取数据。DOM 模型就是把 XML 结构作为一个树形结构处理，从根节点开始，每个节点都可以包含任意个子节点。相比 DOM 模式，SAX 模式占用的内存更小。 +*/ public interface SaxHandler { + /** + * 解析得到 XML 字符数据时执行的回调函数。 + * @param content: String - 元素文本内容。 + */ func characters(content: String): Unit + + /** + * 结束解析 XML 文本时执行的回调函数。 + */ func endDocument(): Unit + + /** + * 结束解析 XML 元素时执行的回调函数。 + * @param name: String - 元素名称。 + */ func endElement(name: String): Unit + + /** + * 开始解析 XML 文本时执行的回调函数。 + */ func startDocument(): Unit + + /** + * 开始解析 XML 元素时执行的回调函数。 + * @param name: String - 元素名称。 + * @param attrs: ArrayList - 元素属性列表。 + */ func startElement(name: String, attrs: ArrayList): Unit } diff --git a/cangjie_libs/fuzz/fuzz.cjd b/cangjie_libs/fuzz/fuzz.cjd index 7b167c5..978ef66 100644 --- a/cangjie_libs/fuzz/fuzz.cjd +++ b/cangjie_libs/fuzz/fuzz.cjd @@ -3,96 +3,537 @@ package fuzz.fuzz // --------------------------- // -----classes // --------------------------- +/** + * 此类继承了 FuzzDataProvider 类型，额外增加了调试信息。 +*/ public class DebugDataProvider <: FuzzDataProvider { + /** + * 将所有数据转换成 UInt8 类型数组。 + * @return Array - UInt8 类型数组。 + */ public override func consumeAll(): Array + + /** + * 将所有数据转换成 Ascii String 类型。 + * @return String - Ascii String 类型实例。 + */ public override func consumeAllAsAscii(): String + + /** + * 将所有数据转换成 utf8 String 类型。 + * @return String - utf8 String 类型实例。 + */ public override func consumeAllAsString(): String + + /** + * 将数据转换成 Ascii String 类型实例。 + * @param maxLength: Int64 - String 类型的最大长度。 + * @return String - String 类型实例。 + */ public override func consumeAsciiString(maxLength: Int64): String + + /** + * 将数据转换成 Bool 类型实例。 + * @return Bool - Bool 类型实例。 + */ public override func consumeBool(): Bool + + /** + * 将指定数量的数据转换成 Bool 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Bool 类型数组。 + */ public override func consumeBools(count: Int64): Array + + /** + * 将数据转换成 Byte 类型实例。 + * @return Byte - Byte 类型实例。 + */ public override func consumeByte(): Byte + + /** + * 将指定数量的数据转换成 Byte 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Byte 类型数组。 + */ public override func consumeBytes(count: Int64): Array + + /** + * 将数据转换成 Float32 类型实例。 + * @return Float32 - Float32 类型实例。 + */ public override func consumeFloat32(): Float32 + + /** + * 将数据转换成 Float64 类型实例。 + * @return Float64 - Float64 类型实例。 + */ public override func consumeFloat64(): Float64 + + /** + * 将数据转换成 Int16 类型实例。 + * @return Int16 - Int16 类型实例。 + */ public override func consumeInt16(): Int16 + + /** + * 将指定数量的数据转换成 Int16 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int16 类型数组。 + */ public override func consumeInt16s(count: Int64): Array + + /** + * 将数据转换成 Int32 类型实例。 + * @return Int32 - Int32 类型实例。 + */ public override func consumeInt32(): Int32 + + /** + * 将指定数量的数据转换成 Int32 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int32 类型数组。 + */ public override func consumeInt32s(count: Int64): Array + + /** + * 将数据转换成 Int64 类型实例。 + * @return Int64 - Int64 类型实例。 + */ public override func consumeInt64(): Int64 + + /** + * 将指定数量的数据转换成 Int64 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int64 类型数组。 + */ public override func consumeInt64s(count: Int64): Array + + /** + * 将数据转换成 Int8 类型实例。 + * @return Int8 - Int8 类型实例。 + */ public override func consumeInt8(): Int8 + + /** + * 将指定数量的数据转换成 Int8 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int8 类型数组。 + */ public override func consumeInt8s(count: Int64): Array + + /** + * 将数据转换成 Rune 类型实例。 + * @return Rune - Rune 类型实例。 + */ public override func consumeRune(): Rune + + /** + * 将数据转换成 utf8 String 类型实例。 + * @param maxLength: Int64 - String 类型的最大长度。 + * @return String - String 类型实例。 + */ public override func consumeString(maxLength: Int64): String + + /** + * 将数据转换成 UInt16 类型实例。 + * @return UInt16 - UInt16 类型实例。 + */ public override func consumeUInt16(): UInt16 + + /** + * 将指定数量的数据转换成 UInt16 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt16 类型数组。 + */ public override func consumeUInt16s(count: Int64): Array + + /** + * 将数据转换成 UInt32 类型实例。 + * @return UInt32 - UInt32 类型实例。 + */ public override func consumeUInt32(): UInt32 + + /** + * 将指定数量的数据转换成 UInt32 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt32 类型数组。 + */ public override func consumeUInt32s(count: Int64): Array + + /** + * 将数据转换成 UInt64 类型实例。 + * @return UInt64 - UInt64 类型实例。 + */ public override func consumeUInt64(): UInt64 + + /** + * 将指定数量的数据转换成 UInt64 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt64 类型数组。 + */ public override func consumeUInt64s(count: Int64): Array + + /** + * 将数据转换成 UInt8 类型实例。 + * @return UInt8 - UInt8 类型实例。 + */ public override func consumeUInt8(): UInt8 + + /** + * 将指定数量的数据转换成 UInt8 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt8 类型数组。 + */ public override func consumeUInt8s(count: Int64): Array + + /** + * 根据 FuzzDataProvider 实例创建 DebugDataProvider 实例。 + * @param dp: FuzzDataProvider - FuzzDataProvider 类型实例。 + * @return DebugDataProvider - 类型实例。 + */ public static func wrap(dp: FuzzDataProvider): DebugDataProvider } +/** + * Fuzzer 类提供了 fuzz 工具的创建。用户提供需要进行 fuzz 测试的函数 targetFunction，以及设置特定的 fuzz 运行参数 args 比如 fuzz 执行次数、初始种子、生成数据最大长度等，可创建相应类型的 Fuzzer。 +*/ public class Fuzzer { + /** + * 根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，创建 Fuzzer 实例。 + * @param targetFunction: (Array) ->Int32 - 以 UInt8 数组为参数，以 Int32 为返回值的目标函数。 + */ public init(targetFunction: (Array) -> Int32) + + /** + * 根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，以及 Fuzz 运行参数，创建 Fuzzer 实例。 + * @param targetFunction: (Array) ->Int32 - 以 UInt8 数组为参数，以 Int32 为返回值的目标函数。 + * @param args: Array - Fuzz 运行参数。 + */ public init(targetFunction: (Array) -> Int32, args: Array) + + /** + * 根据以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数，创建 Fuzzer 实例。 + * @param targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数。 + */ public init(targetFunction: (FuzzDataProvider) -> Int32) + + /** + * 根据以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数，以及 Fuzz 运行参数，创建 Fuzzer 实例。 + * @param targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数。 + * @param args: Array - Fuzz 运行参数。 + */ public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array) + + /** + * 关闭调试信息打印功能，当 FuzzDataProvider.consumeXXX 被调用时，返回值将不被打印到 stdout。 + */ public func disableDebugDataProvider(): Unit + + /** + * 关闭调用 enableFakeCoverage 对 Fuzz 的影响。 + */ public func disableFakeCoverage(): Unit + + /** + * 启用调试信息打印功能，当 FuzzDataProvider.consumeXXX 被调用时，返回值将被打印到 stdout。该功能默认为关闭。 + */ public func enableDebugDataProvider(): Unit + + /** + * 创建一块虚假的覆盖率反馈区域，保持 Fuzz 持续进行。在 FuzzDataProvider 模式下，前几轮运行时可能由于数据不足而导致没有覆盖率，libfuzzer 会退出。该功能默认为关闭。 + */ public func enableFakeCoverage(): Unit + + /** + * 获取 Fuzz 运行参数。 + * @return Array - 当前 Fuzz 运行参数。 + */ public func getArgs(): Array + + /** + * 设置 Fuzz 运行参数。 + * @param args: Array - Fuzz 运行参数。 + */ public func setArgs(args: Array): Unit + + /** + * 设置 Fuzz 目标函数。 + * @param targetFunction: (Array) ->Int32 - 以 UInt8 数组为参数，以 Int32 为返回值的目标函数。 + */ public func setTargetFunction(targetFunction: (Array) -> Int32): Unit + + /** + * 设置 Fuzz 目标函数。 + * @param targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数。 + */ public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): Unit + + /** + * 执行 Fuzz。 + */ public func startFuzz(): Unit } +/** + * 此类用于 Fuzzer 类的构建。 +*/ public class FuzzerBuilder { + /** + * 根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，创建 FuzzerBuilder 实例。 + * @param targetFunction: (Array) ->Int32 - 以 UInt8 数组为参数，以 Int32 为返回值的目标函数。 + */ public init(targetFunction: (Array) -> Int32) + + /** + * 根据以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数，创建 FuzzerBuilder 实例。 + * @param targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数。 + */ public init(targetFunction: (FuzzDataProvider) -> Int32) + + /** + * 生成一个 Fuzzer 实例。 + * @return Fuzzer - Fuzzer 实例。 + */ public func build(): Fuzzer + + /** + * 设置 Fuzz 运行参数。 + * @param args: Array - Fuzz 运行参数。 + * @return FuzzerBuilder - 当前 FuzzerBuilder 实例。 + */ public func setArgs(args: Array): FuzzerBuilder + + /** + * 设置 Fuzz 目标函数。 + * @param targetFunction: (Array) ->Int32 - 以 UInt8 数组为参数，以 Int32 为返回值的目标函数。 + * @return FuzzerBuilder - 当前 FuzzerBuilder 实例。 + */ public func setTargetFunction(targetFunction: (Array) -> Int32): FuzzerBuilder + + /** + * 设置 Fuzz 目标函数。 + * @param targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数，以 Int32 为返回值的目标函数。 + * @return FuzzerBuilder - 当前 FuzzerBuilder 实例。 + */ public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): FuzzerBuilder } +/** + * FuzzDataProvider 是一个工具类，目的是将变异数据的字节流转化为标准的仓颉基本数据。 + * 当前支持的数据结构如下： + * 在数据长度不足时，调用上述大部分虽然会抛出 ExhaustedException，但编写 fuzz 函数时通常并不需要对它进行处理，ExhaustedException 默认会被 fuzz 框架捕获，告诉 libfuzzer 该次运行无效，请继续下一轮变异。随着执行时间的变长，变异数据也会逐渐变长，直到满足 FuzzDataProvider 的需求。 + * 如果达到了 max_len 仍无法满足 FuzzDataProvider 的需求，则进程退出，请修改 fuzz 测试用例（推荐） 或 增大 max_len（不推荐）。 +*/ public open class FuzzDataProvider { + /** + * 变异数据。 + */ public let data: Array + + /** + * 已转化的字节数。 + */ public var offset: Int64 + + /** + * 剩余字节数。 + */ public var remainingBytes: Int64 + + /** + * 将所有数据转换成 UInt8 类型数组。 + * @return Array - UInt8 类型数组。 + */ public open func consumeAll(): Array + + /** + * 将所有数据转换成 Ascii String 类型。 + * @return String - Ascii String 类型实例。 + */ public open func consumeAllAsAscii(): String + + /** + * 将所有数据转换成 utf8 String 类型。 + * @return String - utf8 String 类型实例。 + */ public open func consumeAllAsString(): String + + /** + * 将数据转换成 Ascii String 类型实例。 + * @param maxLength: Int64 - String 类型的最大长度。 + * @return String - String 类型实例。 + */ public open func consumeAsciiString(maxLength: Int64): String + + /** + * 将数据转换成 Bool 类型实例。 + * @return Bool - Bool 类型实例。 + */ public open func consumeBool(): Bool + + /** + * 将指定数量的数据转换成 Bool 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Bool 类型数组。 + */ public open func consumeBools(count: Int64): Array + + /** + * 将数据转换成 Byte 类型实例。 + * @return Byte - Byte 类型实例。 + */ public open func consumeByte(): Byte + + /** + * 将指定数量的数据转换成 Byte 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Byte 类型数组。 + */ public open func consumeBytes(count: Int64): Array + + /** + * 将数据转换成 Float32 类型实例。 + * @return Float32 - Float32 类型实例。 + */ public open func consumeFloat32(): Float32 + + /** + * 将数据转换成 Float64 类型实例。 + * @return Float64 - Float64 类型实例。 + */ public open func consumeFloat64(): Float64 + + /** + * 将数据转换成 Int16 类型实例。 + * @return Int16 - Int16 类型实例。 + */ public open func consumeInt16(): Int16 + + /** + * 将指定数量的数据转换成 Int16 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int16 类型数组。 + */ public open func consumeInt16s(count: Int64): Array + + /** + * 将数据转换成 Int32 类型实例。 + * @return Int32 - Int32 类型实例。 + */ public open func consumeInt32(): Int32 + + /** + * 将指定数量的数据转换成 Int32 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int32 类型数组。 + */ public open func consumeInt32s(count: Int64): Array + + /** + * 将数据转换成 Int64 类型实例。 + * @return Int64 - Int64 类型实例。 + */ public open func consumeInt64(): Int64 + + /** + * 将指定数量的数据转换成 Int64 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int64 类型数组。 + */ public open func consumeInt64s(count: Int64): Array + + /** + * 将数据转换成 Int8 类型实例。 + * @return Int8 - Int8 类型实例。 + */ public open func consumeInt8(): Int8 + + /** + * 将指定数量的数据转换成 Int8 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - Int8 类型数组。 + */ public open func consumeInt8s(count: Int64): Array + + /** + * 将数据转换成 Rune 类型实例。 + * @return Rune - Rune 类型实例。 + */ public open func consumeRune(): Rune + + /** + * 将数据转换成 utf8 String 类型实例。 + * @param maxLength: Int64 - String 类型的最大长度。 + * @return String - String 类型实例。 + */ public open func consumeString(maxLength: Int64): String + + /** + * 将数据转换成 UInt16 类型实例。 + * @return UInt16 - UInt16 类型实例。 + */ public open func consumeUInt16(): UInt16 + + /** + * 将指定数量的数据转换成 UInt16 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt16 类型数组。 + */ public open func consumeUInt16s(count: Int64): Array + + /** + * 将数据转换成 UInt32 类型实例。 + * @return UInt32 - UInt32 类型实例。 + */ public open func consumeUInt32(): UInt32 + + /** + * 将指定数量的数据转换成 UInt32 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt32 类型数组。 + */ public open func consumeUInt32s(count: Int64): Array + + /** + * 将数据转换成 UInt64 类型实例。 + * @return UInt64 - UInt64 类型实例。 + */ public open func consumeUInt64(): UInt64 + + /** + * 将指定数量的数据转换成 UInt64 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt64 类型数组。 + */ public open func consumeUInt64s(count: Int64): Array + + /** + * 将数据转换成 UInt8 类型实例。 + * @return UInt8 - UInt8 类型实例。 + */ public open func consumeUInt8(): UInt8 + + /** + * 将指定数量的数据转换成 UInt8 类型数组。 + * @param count: Int64 - 指定转换的数据量。 + * @return Array - UInt8 类型数组。 + */ public open func consumeUInt8s(count: Int64): Array + + /** + * 使用 Array 类型的数据生成 FuzzDataProvider 类型实例。 + * @param data: Array - 输入的外部数据。 + * @return FuzzDataProvider - 构造的 FuzzDataProvider 类型实例。 + */ public static func withCangjieData(data: Array): FuzzDataProvider + + /** + * 使用 C 指针数据生成 FuzzDataProvider 类型实例。 + * @param data: CPointer - 输入的外部数据。 + * @param length: Int64 - 数据长度。 + * @return FuzzDataProvider - 构造的 FuzzDataProvider 类型实例。 + */ public static unsafe func withNativeData(data: CPointer, length: Int64): FuzzDataProvider } @@ -100,14 +541,28 @@ public open class FuzzDataProvider { // --------------------------- // -----vars // --------------------------- +/** + * Fuzz 版本。 +*/ public let FUZZ_VERSION = "1.0.0" {} // --------------------------- // -----exceptions // --------------------------- +/** + * 此异常为转换数据时，剩余数据不足以转换时抛出的异常。 +*/ public class ExhaustedException <: Exception { + /** + * 创建 ExhaustedException 实例。 + */ public init() + + /** + * 创建 ExhaustedException 实例。 + * @param message: String - 异常提示信息。 + */ public init(message: String) } diff --git a/cangjie_libs/log/log.cjd b/cangjie_libs/log/log.cjd index 6fb8d76..8fc162a 100644 --- a/cangjie_libs/log/log.cjd +++ b/cangjie_libs/log/log.cjd @@ -3,60 +3,322 @@ package log.log // --------------------------- // -----classes // --------------------------- +/** + * 此抽象类提供基础的日志打印和管理功能。 +*/ public abstract class Logger <: Resource { + /** + * 获取和修改日志打印级别。 + */ public open mut prop level: LogLevel + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: String, attrs: Array): Unit + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: () -> String, attrs: Array): Unit + + /** + * 确定是否记录指定日志级别的日志消息。 + * 这个函数允许调用者提前判断日志是否会被丢弃，以避免耗时的日志消息参数计算。 + * @param level: LogLevel - 日志级别。 + * @return Bool - 如果指定的日志级别处于使能状态，则返回 true；否则，返回 false。 + */ public func enabled(level: LogLevel): Bool + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: String, attrs: Array): Unit + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: () -> String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: () -> String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数。 + * @param record: LogRecord - 日志级别。 + */ public open func log(record: LogRecord): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: String, attrs: Array): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: () -> String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: () -> String, attrs: Array): Unit + + /** + * 创建当前对象的副本，新的副本会包含指定的属性。 + * @param attrs: Array - 日志数据键值对属性。 + * @return Logger - Logger 类的对象实例。 + */ public open func withAttrs(attrs: Array): Logger } +/** + * 日志消息的“负载”。 + * 记录结构作为参数传递给 Logger 类的 log方法。日志提供者处理这些结构以显示日志消息。记录是由日志对象自动创建，因此日志用户看不到。 +*/ public class LogRecord { + /** + * 创建一个 LogRecord 实例，指定时间戳，日志打印级别，日志消息和日志数据键值对。 + * @param time: DateTime - 记录日志时的时间戳 + * @param level: LogLevel - 日志级别。 + * @param msg: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public init(time: DateTime, level: LogLevel, msg: String, attrs: Array) + + /** + * 获取或设置日志数据键值对。 + */ public mut prop attrs: Array + + /** + * 获取日志打印级别，只有级别小于等于该值的日志会被打印。 + */ public prop level: LogLevel + + /** + * 获取或设置日志消息。 + */ public mut prop message: String + + /** + * 获取日志打印时的时间戳。 + */ public prop time: DateTime + + /** + * 创建当前对象的副本。 + * @return LogRecord - 当前对象的副本。 + */ public func clone(): LogRecord } +/** + * LogWriter 提供了将仓颉对象序列化成日志输出目标的能力。 + * LogWriter 需要和 interface LogValue 搭配使用，LogWriter 可以通过 writeValue 系列方法来将实现了 LogValue 接口的类型写入到日志输出目标中。 +*/ public abstract class LogWriter { + /** + * 结束序列化当前的 LogValue 数组。 + * @throws IllegalStateException - 当前 writer 没有匹配的 startArray 时。 + */ public func endArray(): Unit + + /** + * 结束序列化当前的 LogValue object。 + * @throws IllegalStateException - 当前 writer 的状态不应该结束一个 LogValue object 时。 + */ public func endObject(): Unit + + /** + * 开始序列化一个新的 LogValue 数组，每一个 startArray 都必须有一个 endArray 对应。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 LogValue array 时。 + */ public func startArray(): Unit + + /** + * 开始序列化一个新的 LogValue object，每一个 startObject 都必须有一个 endObject 对应。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 LogValue object 时。 + */ public func startObject(): Unit + + /** + * 向日志输出目标中写入 Bool 值。 + * @param v: Bool - 待写入的 Bool 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeBool(v: Bool): Unit + + /** + * 向日志输出目标中写入 Float64 值。 + * @param v: Float64 - 待写入的 Float64 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeFloat(v: Float64): Unit + + /** + * 向日志输出目标中写入 DateTime 值。 + * @param v: DateTime - 待写入的 DateTime 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeDateTime(v: DateTime): Unit + + /** + * 向日志输出目标中写入 Duration 值。 + * @param v: Duration - 待写入的 Duration 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeDuration(v: Duration): Unit + + /** + * 向日志输出目标中写入 Int64 值。 + * @param v: Int64 - 待写入的 Int64 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeInt(v: Int64): Unit + + /** + * 向日志输出目标中写入 name。 + * @param v: String - 待写入的 Key 值。 + * @throws IllegalStateException - 当前 writer 的状态不应写入参数 name 指定字符串时。 + */ public func writeKey(v: String): Unit + + /** + * 向日志输出目标中写入 None，具体写成什么格式由 Logger 的提供者自行决定。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeNone(): Unit + + /** + * 向日志输出目标中写入 String 值。 + * @param v: String - 待写入的 String 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeString(v: String): Unit + + /** + * 将实现了 LogValue 接口的类型写入到日志输出目标中。该接口会调用 LogValue 的 writeTo 方法向日志输出目标中写入数据。 + * log 包已经为基础类型 Int64、Float64、Bool、String 类型扩展实现了 LogValue，并且为 DateTime、Duration、 Collection 类型 Array、HashMap 和 TreeMap 以及 Option 扩展实现了 LogValue。 + * @param v: LogValue - 待写入的 LogValue 值。 + * @throws IllegalStateException - 当前 writer 的状态不应该写入 value 时。 + */ public func writeValue(v: LogValue): Unit } +/** + * Logger 的 NO-OP（无操作）实现，会丢弃所有的日志。 +*/ public class NoopLogger <: Logger { + /** + * 创建一个 NoopLogger 实例。 + */ public init() + + /** + * 永远只能获取到 OFF 日志打印级别，设置日志打印级别不会生效。 + */ public mut prop level: LogLevel + + /** + * NOOP 实现。 + */ public func close(): Unit + + /** + * NOOP 实现。 + * @return Bool。 + */ public func isClosed(): Bool + + /** + * NOOP 实现。 + * @param level: LogLevel - 日志级别。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func log(level: LogLevel, message: String, attrs: Array): Unit + + /** + * NOOP 实现。 + * @param level: LogLevel - 日志级别。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func log(level: LogLevel, message: () -> String, attrs: Array): Unit + + /** + * NOOP 实现。 + * @param record: LogRecord - 日志级别。 + */ public func log(record: LogRecord): Unit + + /** + * NOOP 实现。 + * @param attrs: Array - 日志数据键值对。 + */ public func withAttrs(attrs: Array): Logger } @@ -64,8 +326,19 @@ public class NoopLogger <: Logger { // --------------------------- // -----exceptions // --------------------------- +/** + * 用于处理 log 相关的异常。 +*/ public open class LogException <: Exception { + /** + * 无参构造函数。 + */ public init() + + /** + * 根据异常信息创建 LogException 实例。 + * @param message: String - 异常信息。 + */ public init(message: String) } @@ -73,53 +346,142 @@ public open class LogException <: Exception { // --------------------------- // -----funcs // --------------------------- +/** + * 获取 Logger 对象。 + * @param attrs: Array - 日志数据键值对属性，获取的 Logger 对象会包含这些属性。 + * @return Logger - Logger 类的对象实例。 +*/ public func getGlobalLogger(attrs: Array): Logger + +/** + * 设置全局 Logger 对象。 + * @param logger: Logger - 实现了 Logger 类的对象实例。 +*/ public func setGlobalLogger(logger: Logger): Unit + // --------------------------- // -----interfaces // --------------------------- +/** + * 为类型提供序列化到日志输出目标的接口。 + * 与 LogWriter 搭配使用， LogWriter 可以通过 writeValue 来将实现了 LogValue 接口的类型写入到日志输出目标中。 +*/ public interface LogValue { + /** + * 将实现了 LogValue 接口的类型写入参数 w 指定的 LogWriter 实例中。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ func writeTo(w: LogWriter): Unit } +/** + * 为 Bool 类型实现 LogValue 接口。 +*/ extend Bool <: LogValue { + /** + * 提供 Bool 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 Int64 类型实现 LogValue 接口。 +*/ extend Int64 <: LogValue { + /** + * 提供 Int64 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 Float64 类型实现 LogValue 接口。 +*/ extend Float64 <: LogValue { + /** + * 提供 Float64 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 String 类型实现 LogValue 接口。 +*/ extend String <: LogValue { + /** + * 提供 String 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 DateTime 类型实现 LogValue 接口。 +*/ extend DateTime <: LogValue { + /** + * 提供 DateTime 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 Duration 类型实现 LogValue 接口。 +*/ extend Duration <: LogValue { + /** + * 提供 Duration 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 Array 类型实现 LogValue 接口。 +*/ extend Array <: LogValue where T <: LogValue { + /** + * 提供 Array 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 HashMap 类型实现 LogValue 接口。 +*/ extend HashMap <: LogValue where K <: String, V <: LogValue { + /** + * 提供 HashMap 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 TreeMap 类型实现 LogValue 接口。 +*/ extend TreeMap <: LogValue where K <: String, V <: LogValue { + /** + * 提供 TreeMap 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } +/** + * 为 Option 类型实现 LogValue 接口。 +*/ extend Option <: LogValue where T <: LogValue { + /** + * 提供 Option 类型序列化到流的功能。 + * @param w: LogWriter - 写入序列化结果的 LogWriter 实例。 + */ public func writeTo(w: LogWriter): Unit } @@ -127,25 +489,122 @@ extend Option <: LogValue where T <: LogValue { // --------------------------- // -----structs // --------------------------- +/** + * LogLevel 为日志级别结构体。 + * 定义了日志打印的七个级别，级别从低到高分别为 OFF、 FATAL、ERROR、WARN、INFO、DEBUG、TRACE、ALL。 + * 我们期望只有级别小于等于指定打印级别的日志条目会被打印到输出流中。 +*/ public struct LogLevel <: ToString & Comparable { + /** + * 日志级别名。 + */ public let name: String + + /** + * 日志级别值。 + */ public let value: Int32 + + /** + * 常量构造函数，创建 LogLevel 对象。 + * @param name: String - 日志级别名。 + * @param value: Int32 - 日志级别值。 + */ public const init(name: String, value: Int32) + + /** + * 获取一个日志打印级别的静态常量实例，等级为所有。 + */ public static const ALL = LogLevel("ALL", -0x8000_0000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为调试。 + */ public static const DEBUG = LogLevel("DEBUG", 2000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为错误。 + */ public static const ERROR = LogLevel("ERROR", 5000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为严重错误。 + */ public static const FATAL = LogLevel("FATAL", 6000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为通知。 + */ public static const INFO = LogLevel("INFO", 3000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为禁用。 + */ public static const OFF = LogLevel("OFF", 0x7FFF_FFFF) + + /** + * 获取一个日志打印级别的静态常量实例，等级为跟踪。 + */ public static const TRACE = LogLevel("TRACE", 1000) + + /** + * 获取一个日志打印级别的静态常量实例，等级为警告。 + */ public static const WARN = LogLevel("WARN", 4000) + + /** + * 判断当前 LogLevel 类型实例与参数指向的 LogLevel 类型实例的大小关系。 + * @param that: LogLevel - 待与当前实例比较的另一个实例。 + * @return Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。 + */ public func compare(rhs: LogLevel): Ordering + + /** + * 获取日志级别对应的名称。 + * @return String - 当前的日志级别的名称。 + */ public func toString(): String + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别等于 target，返回 true，否则返回 false。 + */ public operator func ==(rhs: LogLevel): Bool + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别不等于 target，返回 true，否则返回 false。 + */ public operator func !=(rhs: LogLevel): Bool + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别大于等于 target，返回 true，否则返回 false。 + */ public operator func >=(rhs: LogLevel): Bool + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别小于等于 target，返回 true，否则返回 false。 + */ public operator func <=(rhs: LogLevel): Bool + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别大于 target，返回 true，否则返回 false。 + */ public operator func >(rhs: LogLevel): Bool + + /** + * 比较日志级别高低。 + * @param rhs: LogLevel - 将当前日志级别和 target 进行比较。 + * @return Bool - 如果当前日志级别小于 target，返回 true，否则返回 false。 + */ public operator func <(rhs: LogLevel): Bool } @@ -153,6 +612,9 @@ public struct LogLevel <: ToString & Comparable { // --------------------------- // -----types // --------------------------- -public type Attr = (String, LogValue) {} +/** + * 日志消息的键值对类型，是 (String, LogValue) 的类型别名。 +*/ +public type Attr = (String, LogValue) diff --git a/cangjie_libs/logger/logger.cjd b/cangjie_libs/logger/logger.cjd index bd2baad..1d17f82 100644 --- a/cangjie_libs/logger/logger.cjd +++ b/cangjie_libs/logger/logger.cjd @@ -3,69 +3,414 @@ package logger.logger // --------------------------- // -----classes // --------------------------- +/** + * 此类实现了输出 JSON 格式的日志打印功能，形如 {"time":"2024-07-27T11:51:59+08:00","level":"INFO","msg":"foo","name":"bar"}。 +*/ public class JsonLogger <: Logger { + /** + * 创建 JsonLogger 对象。 + * @param output: OutputStream - 绑定的输出流，日志格式化后将写入该输出流。 + */ public init(output: OutputStream) + + /** + * 获取和修改日志打印级别。 + */ public open mut prop level: LogLevel + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: String, attrs: Array): Unit + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: () -> String, attrs: Array): Unit + + /** + * 确定是否记录指定日志级别的日志消息。 + * 这个函数允许调用者提前判断日志是否会被丢弃，以避免耗时的日志消息参数计算。 + * @param level: LogLevel - 日志级别。 + * @return Bool - 如果指定的日志级别处于使能状态，则返回 true；否则，返回 false。 + */ public func enabled(level: LogLevel): Bool + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: String, attrs: Array): Unit + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: () -> String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: () -> String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数。 + * @param record: LogRecord - 日志级别。 + */ public open func log(record: LogRecord): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: String, attrs: Array): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: () -> String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: () -> String, attrs: Array): Unit + + /** + * 创建当前对象的副本，新的副本会包含指定的属性。 + * @param attrs: Array - 日志数据键值对属性。 + * @return Logger - Logger 类的对象实例。 + */ public open func withAttrs(attrs: Array): Logger } +/** + * 此类实现了输出文本格式的日志打印功能，形如 2024-07-27T11:50:47.6616733+08:00 INFO foo name="bar"。 +*/ public class SimpleLogger <: Logger { + /** + * 创建 SimpleLogger 对象。 + * @param output: OutputStream - 绑定的输出流，日志格式化后将写入该输出流。 + */ public init(output: OutputStream) + + /** + * 获取和修改日志打印级别。 + */ public open mut prop level: LogLevel + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: String, attrs: Array): Unit + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: () -> String, attrs: Array): Unit + + /** + * 确定是否记录指定日志级别的日志消息。 + * 这个函数允许调用者提前判断日志是否会被丢弃，以避免耗时的日志消息参数计算。 + * @param level: LogLevel - 日志级别。 + * @return Bool - 如果指定的日志级别处于使能状态，则返回 true；否则，返回 false。 + */ public func enabled(level: LogLevel): Bool + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: String, attrs: Array): Unit + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: () -> String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: () -> String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数。 + * @param record: LogRecord - 日志级别。 + */ public open func log(record: LogRecord): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: String, attrs: Array): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: () -> String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: () -> String, attrs: Array): Unit + + /** + * 创建当前对象的副本，新的副本会包含指定的属性。 + * @param attrs: Array - 日志数据键值对属性。 + * @return Logger - Logger 类的对象实例。 + */ public open func withAttrs(attrs: Array): Logger } +/** + * 此类实现了输出文本格式的日志打印功能，形如 time=2024-07-27T11:52:40.3226881+08:00 level="INFO" msg="foo" name="bar"。 +*/ public class TextLogger <: Logger { + /** + * 创建 TextLogger 对象。 + * @param output: OutputStream - 绑定的输出流，日志格式化后将写入该输出流。 + */ public init(output: OutputStream) + + /** + * 获取和修改日志打印级别。 + */ public open mut prop level: LogLevel + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: String, attrs: Array): Unit + + /** + * 打印 DEBUG 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func debug(message: () -> String, attrs: Array): Unit + + /** + * 确定是否记录指定日志级别的日志消息。 + * 这个函数允许调用者提前判断日志是否会被丢弃，以避免耗时的日志消息参数计算。 + * @param level: LogLevel - 日志级别。 + * @return Bool - 如果指定的日志级别处于使能状态，则返回 true；否则，返回 false。 + */ public func enabled(level: LogLevel): Bool + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: String, attrs: Array): Unit + + /** + * 打印 ERROR 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func error(message: () -> String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: String, attrs: Array): Unit + + /** + * 打印 FATAL 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func fatal(message: () -> String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: String, attrs: Array): Unit + + /** + * 打印 INFO 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func info(message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: String, attrs: Array): Unit + + /** + * 打印日志的通用函数，需指定日志级别。 + * @param level: LogLevel - 日志级别。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public open func log(level: LogLevel, message: () -> String, attrs: Array): Unit + + /** + * 打印日志的通用函数。 + * @param record: LogRecord - 日志级别。 + */ public open func log(record: LogRecord): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: String, attrs: Array): Unit + + /** + * 打印 TRACE 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func trace(message: () -> String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: String, attrs: Array): Unit + + /** + * 打印 WARN 级别的日志的便捷函数。 + * @param message: () -> String - 日志消息。 + * @param attrs: Array - 日志数据键值对。 + */ public func warn(message: () -> String, attrs: Array): Unit + + /** + * 创建当前对象的副本，新的副本会包含指定的属性。 + * @param attrs: Array - 日志数据键值对属性。 + * @return Logger - Logger 类的对象实例。 + */ public open func withAttrs(attrs: Array): Logger } diff --git a/cangjie_libs/net/http.cjd b/cangjie_libs/net/http.cjd index d4963cd..5835830 100644 --- a/cangjie_libs/net/http.cjd +++ b/cangjie_libs/net/http.cjd @@ -3,287 +3,1530 @@ package net.http // --------------------------- // -----classes // --------------------------- +/** + * 发送 Http request、随时关闭等。用户可以通过 Client 实例发送 HTTP/1.1 或 HTTP/2 请求。 +*/ public class Client { + /** + * 客户端是否会自动进行重定向，304 状态码默认不重定向。 + */ public prop autoRedirect: Bool + + /** + * 客户端调用此函数获取到服务器的连接。 + */ public prop connector: (SocketAddress) -> StreamingSocket + + /** + * 用于存储客户端所有 Cookie，如果配置为 None，则不会启用 Cookie。 + */ public prop cookieJar: ?CookieJar + + /** + * 客户端 HTTP/2 是否支持服务器推送，默认值为 true。 + */ public prop enablePush: Bool + + /** + * 获取客户端 HTTP/2 Hpack 动态表的初始值，默认值为 4096。 + */ public prop headerTableSize: UInt32 + + /** + * 获取客户端 http 代理，默认使用系统环境变量 http_proxy 的值，用字符串表示，格式为："http://host:port"，例如："http://192.168.1.1:80"。 + */ public prop httpProxy: String + + /** + * 获取客户端 https 代理，默认使用系统环境变量 https_proxy 的值，用字符串表示，格式为："http://host:port"，例如："http://192.168.1.1:443"。 + */ public prop httpsProxy: String + + /** + * 获取客户端 HTTP/2 流控窗口初始值，默认值为 65535 ，取值范围为 0 至 2^31 - 1。 + */ public prop initialWindowSize: UInt32 + + /** + * 获取客户端日志记录器，设置 logger.level 将立即生效，记录器应该是线程安全的。 + */ public prop logger: Logger + + /** + * 获取客户端 HTTP/2 初始最大并发流数量，默认值为 2^31 - 1。 + */ public prop maxConcurrentStreams: UInt32 + + /** + * 获取客户端 HTTP/2 初始最大帧大小。默认值为 16384. 取值范围为 2^14 至 2^24 - 1。 + */ public prop maxFrameSize: UInt32 + + /** + * 获取客户端支持的 HTTP/2 最大头部（Header）大小。这个大小指的是响应头部中所有头部字段（Header Field）的最大允许长度之和，其中包括所有字段名称（name）的长度、字段值（value）的长度以及每个字段自动添加的伪头开销（通常每个字段会有32字节的开销，这包括了HTTP/2协议本身为头部字段添加的伪头部信息）。默认情况下，这个最大长度被设置为 UInt32.Max。 + */ public prop maxHeaderListSize: UInt32 + + /** + * 配置 HTTP/1.1 客户端使用的连接池的大小，亦可表示对同一个主机（host:port）同时存在的连接数的最大值。 + */ public prop poolSize: Int64 + + /** + * 获取客户端设定的读取整个响应的超时时间，默认值为 15s。 + */ public prop readTimeout: Duration + + /** + * 获取客户端设定的写请求的超时时间，默认值为 15s。 + */ public prop writeTimeout: Duration + + /** + * 关闭客户端建立的所有连接，调用后不能继续发送请求。 + */ public func close(): Unit + + /** + * 发送 CONNECT 请求与服务器建立隧道，返回建连成功后的连接，连接由用户负责关闭。服务器返回 2xx 表示建连成功，否则建连失败（不支持自动重定向，3xx 也视为失败）。 + * @param url: String - 请求的 url。 + * @param header!: HttpHeaders - 请求头，默认为空请求头。 + * @param version!: Protocol - 请求的协议，默认为 HTTP1_1。 + * @return (HttpResponse,?StreamingSocket) - 返回元组类型，其中 HttpResponse 实例表示服务器返回的响应体，Option 实例表示请求成功时返回 headers 之后连接。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func connect(url: String, header!: HttpHeaders = HttpHeaders(), version!: Protocol = HTTP1_1): (HttpResponse, ?StreamingSocket) + + /** + * 请求方法为 DELETE 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func delete(url: String): HttpResponse + + /** + * 请求方法为 GET 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func get(url: String): HttpResponse + + /** + * 获取客户端设定的 TLS 层配置。 + * @return ?TlsClientConfig - 客户端设定的 TLS 层配置，如果没有设置则返回 None。 + */ public func getTlsConfig(): ?TlsClientConfig + + /** + * 请求方法为 HEAD 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func head(url: String): HttpResponse + + /** + * 请求方法为 OPTIONS 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func options(url: String): HttpResponse + + /** + * 请求方法为 POST 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: Array - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func post(url: String, body: Array): HttpResponse + + /** + * 请求方法为 POST 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: InputStream - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func post(url: String, body: InputStream): HttpResponse + + /** + * 请求方法为 POST 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: String - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func post(url: String, body: String): HttpResponse + + /** + * 请求方法为 PUT 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: Array - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func put(url: String, body: Array): HttpResponse + + /** + * 请求方法为 PUT 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: InputStream - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func put(url: String, body: InputStream): HttpResponse + + /** + * 请求方法为 PUT 的便捷请求函数。 + * @param url: String - 请求的 url。 + * @param body: String - 请求体。 + * @return HttpResponse - 服务端返回的响应。 + * @throws UrlSyntaxException - 当参数 url 不符合 URL 解析规范时，抛出异常。 + */ public func put(url: String, body: String): HttpResponse + + /** + * 通用请求函数，发送 HttpRequest 到 url 中的服务器，接收 HttpResponse。 + * @param req: HttpRequest - 发送的请求。 + * @return HttpResponse - 服务端返回处理该请求的响应。 + * @throws UrlSyntaxException - 请求中 URL 错误时抛此异常。 + */ public func send(req: HttpRequest): HttpResponse + + /** + * 发送请求并升级协议，用户设置请求头，返回升级后的连接（如果升级成功），连接由用户负责关闭。 + * @param req: HttpRequest - 升级时发送的请求。 + * @return (HttpResponse,?StreamingSocket) - 返回一个元组，HttpResponse 实例表示服务器返回的响应，?StreamingSocket 实例表示获取的底层连接，升级失败时为 None。 + * @throws HttpException - 请求报文或响应报文不符合协议； 请求报文不含 Upgrade 头； 发送 CONNECT 请求； 发送带 body 的 TRACE 请求； + */ public func upgrade(req: HttpRequest): (HttpResponse, ?StreamingSocket) } +/** + * 用于 Client 实例的构建，Client 没有公开的构造函数，用户只能通过 ClientBuilder 得到 Client 实例。ClientBuilder 文档中未明确说明支持版本的配置，在 HTTP/1.1 与 HTTP/2 都会生效。 +*/ public class ClientBuilder { + /** + * 创建新的 ClientBuilder 实例。 + */ public init() + + /** + * 配置客户端是否会自动进行重定向。重定向会请求 Location 头的资源，协议规定，Location 只能包含一个 URI 引用Location = URI-reference，详见 RFC 9110 10.2.2.。304 状态码默认不重定向。 + * @param auto: Bool - 默认值为 true，即开启自动重定向。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func autoRedirect(auto: Bool): ClientBuilder + + /** + * 构造 Client 实例。 + * @return Client - 用当前 ClientBuilder 实例中的配置构建的 Client 实例。 + * @throws IllegalArgumentException - 配置项有非法参数时抛出此异常。 + */ public func build(): Client + + /** + * 客户端调用此函数获取到服务器的连接。 + * @param connector: (SocketAddress) ->StreamingSocket - 入参为 SocketAddress 实例，返回值类型为 StreamingSocket 的函数类型。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func connector(connector: (SocketAddress)->StreamingSocket): ClientBuilder + + /** + * 用于存储客户端所有 Cookie。 + * @param cookieJar: ?CookieJar - 默认使用一个空的 CookieJar，如果配置为 None 则不会启用 Cookie。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func cookieJar(cookieJar: ?CookieJar): ClientBuilder + + /** + * 配置客户端 HTTP/2 是否支持服务器推送。 + * @param enable: Bool - 默认值 true。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func enablePush(enable: Bool): ClientBuilder + + /** + * 配置客户端 HTTP/2 Hpack 动态表初始值。 + * @param size: UInt32 - 默认值 4096。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func headerTableSize(size: UInt32): ClientBuilder + + /** + * 设置客户端 http 代理，默认使用系统环境变量 http_proxy 的值。 + * @param addr: String - 格式为："http://host:port"，例如："http://192.168.1.1:80"。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func httpProxy(addr: String): ClientBuilder + + /** + * 设置客户端 https 代理，默认使用系统环境变量 https_proxy 的值。 + * @param addr: String - 格式为："http://host:port"，例如："http://192.168.1.1:443"。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func httpsProxy(addr: String): ClientBuilder + + /** + * 配置客户端 HTTP/2 流控窗口初始值。 + * @param size: UInt32 - 默认值 65535 ， 取值范围为 0 至 2^31 - 1。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func initialWindowSize(size: UInt32): ClientBuilder + + /** + * 设定客户端的 logger，默认 logger 级别为 INFO，logger 内容将写入 Console.stdout。 + * @param logger: Logger - 需要是线程安全的，默认使用内置线程安全 logger。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func logger(logger: Logger): ClientBuilder + + /** + * 配置客户端 HTTP/2 初始最大并发流数量。 + * @param size: UInt32 - 默认值为 2^31 - 1。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func maxConcurrentStreams(size: UInt32): ClientBuilder + + /** + * 配置客户端 HTTP/2 初始最大帧大小。 + * @param size: UInt32 - 默认值为 16384. 取值范围为 2^14 至 2^24 - 1。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func maxFrameSize(size: UInt32): ClientBuilder + + /** + * 获取客户端支持的 HTTP/2 最大头部（Header）大小。这个大小指的是响应头部中所有头部字段（Header Field）的最大允许长度之和，其中包括所有字段名称（name）的长度、字段值（value）的长度以及每个字段自动添加的伪头开销（通常每个字段会有32字节的开销，这包括了HTTP/2协议本身为头部字段添加的伪头部信息）。默认情况下，这个最大长度被设置为 UInt32.Max。 + * @param size: UInt32 - 客户端接收的 HTTP/2 响应 headers 最大长度。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func maxHeaderListSize(size: UInt32): ClientBuilder + + /** + * 调用此函数后，客户端不使用任何代理。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func noProxy(): ClientBuilder + + /** + * 配置 HTTP/1.1 客户端使用的连接池的大小，亦可表示对同一个主机（host:port）同时存在的连接数的最大值。 + * @param size: Int64 - 默认 10，poolSize 需要大于 0。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + * @throws HttpException - 如果传参小于等于 0，则会抛出该异常。 + */ public func poolSize(size: Int64): ClientBuilder + + /** + * 设定客户端读取一个响应的最大时长。 + * @param timeout: Duration - 默认 15s，Duration.Max 代表不限制，如果传入负的 Duration 将被替换为 Duration.Zero + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func readTimeout(timeout: Duration): ClientBuilder + + /** + * 设置 TLS 层配置，默认不对其进行设置。 + * @param config: TlsClientConfig - 设定支持 tls 客户端需要的配置信息。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func tlsConfig(config: TlsClientConfig): ClientBuilder + + /** + * 设定客户端发送一个请求的最大时长。 + * @param timeout: Duration - 默认 15s，Duration.Max 代表不限制，如果传入负的 Duration 将被替换为 Duration.Zero。 + * @return ClientBuilder - 当前 ClientBuilder 实例的引用。 + */ public func writeTimeout(timeout: Duration): ClientBuilder } +/** + * HTTP 本身是无状态的，server 为了知道 client 的状态，提供个性化的服务，便可以通过 Cookie 来维护一个有状态的会话。 +*/ public class Cookie { + /** + * 获取 Cookie 对象的 cookie-name 值。 + */ public prop cookieName: String + + /** + * 获取 Cookie 对象的 cookie-value 值。 + */ public prop cookieValue: String + + /** + * 获取 Cookie 对象的 domain-av 值。 + */ public prop domain: String + + /** + * 获取 Cookie 对象的 expires-av 值。 + */ public prop expires: ?DateTime + + /** + * 获取 Cookie 对象的 httpOnly-av 值。 + */ public prop httpOnly: Bool + + /** + * 获取 Cookie 对象的 max-age-av 值。 + */ public prop maxAge: ?Int64 + + /** + * 获取未被解析的属性。 + */ public prop others: ArrayList + + /** + * 获取 Cookie 对象的 path-av 值。 + */ public prop path: String + + /** + * 获取 Cookie 对象的 secure-av 值。 + */ public prop secure: Bool + + /** + * 提供 Cookie 对象的公开构造器说明：该构造器会检查传入的各项属性是否满足协议要求，如果不满足则会产生 IllegalArgumentException。具体要求见 RFC 6265 4.1.1.。 + * @param name: String - cookie-name 属性。 name = token token = 1*tchar tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA + * @param value: String - cookie-value 属性。 value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE ) cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E ; US-ASCII characters excluding CTLs, ; whitespace DQUOTE, comma, semicolon, ; and backslash + * @param expires!: ?DateTime - 设置 Cookie 的过期时间，默认为 None，时间必须在 1601 年之后。 + * @param maxAge!: ?Int64 - Cookie 的最大生命周期，默认为 None，如果 Cookie 既有 expires 属性，也有 maxAge，则表示该 Cookie 只维护到会话结束（维护到 Client 关闭之前，Client 关闭之后设置了过期的 Cookie 也不再维护）。 max-age-av = "Max-Age=" non-zero-digit *DIGIT non-zero-digit = %x31-39 ; digits 1 through 9 DIGIT = %x30-39 ; digits 0 through 9 + * @param domain!: String - 默认为空字符串，表示该收到该 Cookie 的客户端只会发送该 Cookie 给原始服务器。如果设置了合法的 domain，则收到该 Cookie 的客户端只会发送该 Cookie 给所有该 domain 的子域（且满足其他属性条件要求才会发）。 domain = | " " ::=