🥮 mooncakes.io
    Sign in

    q2316367743/open-list/core does not have a README file

    OpenListError

    source
    pub(all) suberror OpenListError {
      Http(
    HttpError    )
      Api(ApiError)
      Decode(String)
    }

    客户端可能抛出的全部错误。

    OpenListError::code

    source
    fn OpenListError::code(self : OpenListError) -> Int?

    业务错误码；不是 Api 错误时是 None。

    OpenListError::message

    source
    fn OpenListError::message(self : OpenListError) -> String

    人类可读的一行错误消息，适合直接写日志。

    OpenListError::status

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

    对应的 HTTP 状态码；传输层没拿到响应时是 None。

    ApiError

    source
    pub struct ApiError {
      code : Int
      message : String
      status : Int
      data : Json?
    } derive(
    Debug    )

    服务端返回的业务错误：HTTP 响应已经到达，但信封里的 code 不是 200。

    OpenList 用 code 表达业务结果，HTTP 状态码只是它的粗粒度映射， 所以两边都保留：code/message 来自信封，status 来自 HTTP 状态行。

    ApiError::to_repr

    source

    显式声明 derive 出来的 Debug 实现以普通方法暴露，避免工具链的 「隐式提升为方法」弃用告警（行为与 derive 完全一致）。

    ArchiveContent

    source
    pub struct ArchiveContent {
      obj : ObjResp
      children : Array[ArchiveContent]
    }

    归档条目的内容项（POST /api/fs/archive/meta 的文件树节点）。

    与 FsGetResponse 一样，Go 内嵌了 ObjResp；这里放在 obj 字段里。

    ArchiveContent::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    ArchiveMetaResponse

    source
    pub struct ArchiveMetaResponse {
      comment : String
      encrypted : Bool
      content : Array[ArchiveContent]
      sort : ListSort?
      raw_url : String
      sign : String
    }

    POST /api/fs/archive/meta 的响应。

    ArchiveMetaResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    Client

    source
    pub struct Client {
      // private fields
    }

    六个域子模块共享的 HTTP 客户端与认证状态。

    由根包的 create_open_list_client 创建，域子模块各持有它的一份拷贝。 token 存在共享的 @ref.Ref 里，因此各拷贝看到的是同一份登录状态： 认证模块登录成功后，文件系统模块立刻就能用上新 token。

    OpenList 的认证头形如 Authorization: <token>，没有 Bearer 前缀。

    Client::credentials

    source
    fn Client::credentials(self : Client) -> Credentials

    当前使用的认证凭证。

    Client::ensure_token

    source
    async fn Client::ensure_token(self : Client) -> String raise OpenListError

    拿到一个可用 token：永久 token 直接返回；账号密码则在首次使用时登录换取。

    已知限制：多个请求同时首次触发登录时，可能各发一次登录请求（服务端会 各自签发 token，最后一次写入生效），不会造成状态错乱。

    Client::is_logged_in

    source
    fn Client::is_logged_in(self : Client) -> Bool

    是否已有可用 token（永久 token，或账号密码换来的限时 token）。

    Client::new

    source
    fn Client::new(settings : Settings, credentials : Credentials, transport? : &
    Transport    ) -> Client

    创建共享客户端。transport 只在测试里注入 Mock 传输层，生产不传。

    Client::password_login

    source
    async fn Client::password_login(self : Client, credentials : PasswordCredentials) -> String raise OpenListError

    用账号密码换限时 token（POST /api/auth/login）。

    这是唯一会主动登录的地方，它不经过 ensure_token，所以不会递归。 常见的失败是 401（用户名或密码错误）与 402（两步验证码错误）。

    Client::request

    source
    async fn Client::request(self : Client, http_method : 
    Method    , path : String, query? : Json, body? : Json, headers? : Array[(String, String)]) -> Json raise OpenListError

    发送一个 JSON 请求，返回信封里的 data（原样，不做 null 剔除）。

    这是六个域子模块的统一出口，也是留给使用者的逃生通道：官方客户端没有 封装的端点可以直接用它打到 /api/...（见 docs/08-unsupported-endpoints.md）。

    认证自动完成：收到 401 且凭证是账号密码时，会清掉旧 token 重登一次再 重试一次；用永久 token 时直接报错（重试也没有意义）。

    Client::send_form

    source
    async fn Client::send_form(self : Client, http_method : 
    Method    , path : String, form : 
    FormData    , headers? : Array[(String, String)]) -> Json raise OpenListError

    发送 multipart/form-data 请求（PUT /api/fs/form）。

    Client::send_stream

    source
    async fn Client::send_stream(self : Client, http_method : 
    Method    , path : String, reader : &
    Reader    , content_length? : Int, headers? : Array[(String, String)]) -> Json raise OpenListError

    发送请求体来自流的请求（二进制上传）。

    用于 /api/fs/put、/api/fs/multipart/chunk 这类「body 就是原始字节」的 端点——moonhttp 的请求体构造器没有裸字节那一档，二进制只能走流。 与 request 一样检查信封，但不做 401 重试。

    Client::set_token

    source
    fn Client::set_token(self : Client, token : String?) -> Unit

    直接覆盖 token，用于从外部持久化状态恢复会话，或主动让 token 失效。

    Client::settings

    source
    fn Client::settings(self : Client) -> Settings

    连接设置。

    Client::token

    source
    fn Client::token(self : Client) -> String?

    当前 token；尚未登录（账号密码凭证且还没登录过）时是 None。

    Credentials

    source
    pub(all) enum Credentials {
      Token(String)
      Password(PasswordCredentials)
    }

    认证凭证：OpenList 支持的两种认证方式二选一。

    • Token：后台生成的永久 token，直接拿来用；
    • Password：账号密码，客户端在第一次需要认证的请求前自动登录， 换取一个限时 token（服务端过期后由客户端在收到 401 时重登一次）。

    Credentials::password

    source
    fn Credentials::password(username : String, password : String, otp_code? : String) -> Credentials

    创建账号密码凭证的便捷构造器。

    Credentials::token

    source
    fn Credentials::token(token : String) -> Credentials

    用永久 token 创建凭证（后台「设置 → 其他 → 令牌」生成的那个）。

    DirResp

    source
    pub struct DirResp {
      name : String
      modified : String
    }

    目录项（POST /api/fs/dirs 用，只有名字与修改时间）。
    impl FromJson for DirResp

    DirResp::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    DriverConfig

    source
    pub struct DriverConfig {
      name : String
      local_sort : Bool
      only_proxy : Bool
      no_cache : Bool
      no_upload : Bool
      need_ms : Bool
      default_root : String
      alert : String
      only_indices : Bool
      prefer_proxy : Bool
    }

    驱动能力声明。

    DriverConfig::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    DriverInfo

    source
    pub struct DriverInfo {
      common : Array[DriverItem]
      additional : Array[DriverItem]
      config : DriverConfig
    }

    一个驱动（或一个存储驱动实例）的完整描述。

    DriverInfo::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    DriverItem

    source
    pub struct DriverItem {
      name : String
      item_type : String
      default : String
      options : String
      required : Bool
      help : String
    }

    驱动的一个配置项描述。

    DriverItem::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    FsGetResponse

    source
    pub struct FsGetResponse {
      obj : ObjResp
      raw_url : String
      readme : String
      header : String
      provider : String
      related : Array[ObjResp]
    }

    POST /api/fs/get 的响应。

    Go 服务端把 ObjResp 内嵌进来，对象字段与 raw_url 等在同一层； MoonBit 没有结构体内嵌，所以对象部分放在 obj 里（解码时仍从同一个 扁平对象读）。

    FsGetResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    FsListResponse

    source
    pub struct FsListResponse {
      content : Array[ObjResp]
      total : Int64
      readme : String
      header : String
      write : Bool
      write_content_bypass : Bool
      provider : String
      direct_upload_tools : Array[String]
    }

    POST /api/fs/list 的响应。

    FsListResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    IndexProgress

    source
    pub struct IndexProgress {
      obj_count : Int64
      is_done : Bool
      last_done_time : String?
      error : String
    }

    索引构建进度（GET /api/admin/index/progress）。

    IndexProgress::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    InitStatus

    source
    pub struct InitStatus {
      initialized : Bool
    }

    系统初始化状态（GET /api/public/init_status）。

    InitStatus::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。
    pub struct Link {
      url : String
      header : Map[String, Array[String]]
      concurrency : Int
      part_size : Int
      content_length : Int64
    }

    直链（POST /api/fs/link 的响应）。

    服务端在驱动不支持直链时只会填 url；支持多线程加速的驱动还会给出 concurrency 与 part_size。

    Link::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    ListSort

    source
    pub struct ListSort {
      order_by : String
      order_direction : String
      extract_folder : String
    }

    列表排序设置（Go 的 model.Sort，被存储、分享、归档元数据共用）。

    ListSort::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    Meta

    source
    pub(all) struct Meta {
      id : UInt
      path : String
      read_users : Array[UInt]
      read_users_sub : Bool
      write_users : Array[UInt]
      write_users_sub : Bool
      password : String
      p_sub : Bool
      write : Bool
      w_sub : Bool
      hide : String
      h_sub : Bool
      readme : String
      r_sub : Bool
      header : String
      header_sub : Bool
    } derive(ToJson)

    路径元数据（/api/admin/meta/* 的读写对象）。

    Go 里 read_users_sub 这类布尔字段表示「是否连同子目录生效」， 名字里的 _sub 后缀不能省。
    impl FromJson for Meta

    Meta::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    Meta::to_json

    source
    fn Meta::to_json(Meta) -> Json

    显式声明 derive 出来的 ToJson 实现以普通方法暴露。

    MultipartInitResponse

    source
    pub struct MultipartInitResponse {
      snapshot : SessionSnapshot
      resumed : Bool
    }

    POST /api/fs/multipart/init 的响应：会话快照 + 是否是「续传」。

    MultipartInitResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    ObjResp

    source
    pub struct ObjResp {
      name : String
      size : Int64
      is_dir : Bool
      modified : String
      created : String
      sign : String
      thumb : String
      obj_type : Int
      hashinfo : String
      hash_info : Map[String, String]
      mount_details : StorageDetails?
    }

    文件系统对象（文件或目录）。
    impl FromJson for ObjResp

    ObjResp::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    PageResult

    source
    pub struct PageResult[T] {
      content : Array[T]
      total : Int64
    }

    OpenList 分页接口的统一结果。
    impl FromJson for PageResult[T]

    PageResult::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露，避免工具链的 「隐式提升为方法」弃用告警（行为与 derive 完全一致）。

    PageResult::new

    source
    fn[T] PageResult::new(content : Array[T], total : Int64) -> PageResult[T]

    创建分页结果。

    PasswordCredentials

    source
    pub struct PasswordCredentials {
      username : String
      password : String
      otp_code : String?
    }

    账号密码凭证。

    OpenList 服务端会在这条通道上做静态哈希，所以这里传明文密码； 想做「前端已预哈希」的登录请改用 login_hash。

    PasswordCredentials::new

    source
    fn PasswordCredentials::new(username : String, password : String, otp_code? : String) -> PasswordCredentials

    创建账号密码凭证。

    SSHPublicKey

    source
    pub struct SSHPublicKey {
      id : UInt
      title : String
      fingerprint : String
      added_time : String
      last_used_time : String
    }

    SSH 公钥。

    SSHPublicKey::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    SearchResult

    source
    pub struct SearchResult {
      parent : String
      name : String
      is_dir : Bool
      size : Int64
      obj_type : Int
    }

    搜索结果项（POST /api/fs/search 用）。

    SearchResult::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    SessionSnapshot

    source
    pub struct SessionSnapshot {
      upload_id : String
      state : String
      attempt : Int
      path : String
      size : Int64
      chunk_size : Int64
      total_chunks : Int
      received : Array[Array[Int]]
      received_bytes : Int64
      frontier : Int
      storage_progress : Double
      error : String?
    }

    分片上传会话的快照（/api/fs/multipart/* 的响应载荷）。

    SessionSnapshot::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    SettingItem

    source
    pub(all) struct SettingItem {
      key : String
      value : String
      help : String
      item_type : String
      options : String
      group : Int
      flag : Int
      index : UInt
    }

    一项系统设置（/api/admin/setting/* 的读写对象）。

    SettingItem::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    SettingItem::to_json

    source
    fn SettingItem::to_json(self : SettingItem) -> Json

    显式声明手写的 ToJson 实现以普通方法暴露。

    Settings

    source
    pub struct Settings {
      base_url : String
      timeout : Int?
    }

    连接一台 OpenList 服务器所需的设置。

    这些值在创建客户端时被固化进 moonhttp 的默认配置：base_url 成为 请求 URL 的前缀，timeout 成为默认超时；之后每个请求只给相对路径。

    Settings::new

    source
    fn Settings::new(base_url : String, timeout? : Int) -> Settings

    创建连接设置。

    let settings = @core.Settings::new("https://openlist.example.com")

    SharingResponse

    source
    pub struct SharingResponse {
      id : String
      expires : String?
      pwd : String
      accessed : Int
      max_accessed : Int
      disabled : Bool
      remark : String
      readme : String
      header : String
      order_by : String
      order_direction : String
      extract_folder : String
      files : Array[String]
      creator : String
      creator_role : Int
    }

    一条分享记录。

    SharingResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    Storage

    source
    pub(all) struct Storage {
      id : UInt
      mount_path : String
      order : Int
      driver : String
      cache_expiration : Int
      custom_cache_policies : String
      status : String
      addition : String
      remark : String
      modified : String
      disabled : Bool
      disable_index : Bool
      enable_sign : Bool
      order_by : String
      order_direction : String
      extract_folder : String
      web_proxy : Bool
      webdav_policy : String
      proxy_range : Bool
      down_proxy_url : String
      disable_proxy_sign : Bool
    } derive(ToJson)

    存储挂载配置。

    Go 把 model.Sort 与 model.Proxy 内嵌在这里，JSON 上仍是扁平字段， 这里也摊平。
    impl FromJson for Storage

    Storage::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    Storage::to_json

    source
    fn Storage::to_json(Storage) -> Json

    显式声明 derive 出来的 ToJson 实现以普通方法暴露。

    StorageDetails

    source
    pub struct StorageDetails {
      driver_name : String
      total_space : Int64
      free_space : Int64
    }

    挂载点容量信息。

    只有登录用户（非游客）且管理员没有隐藏存储详情时才会随文件对象返回。

    StorageDetails::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    TaskInfo

    source
    pub struct TaskInfo {
      id : String
      name : String
      creator : String
      creator_role : Int
      state : String
      status : String
      progress : Double
      start_time : String?
      end_time : String?
      total_bytes : Int64
      error : String
    }

    异步任务的描述（/api/fs/put 带 As-Task: true 时随响应返回）。

    本客户端没有封装 /api/task/* 的任务管理端点，这个模型只用来读取 「任务已创建」的结果（任务 ID、状态、进度）。

    TaskInfo::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    User

    source
    pub(all) struct User {
      id : UInt
      username : String
      password : String
      base_path : String
      role : Int
      disabled : Bool
      permission : Int
      sso_id : String
      allow_ldap : Bool
    } derive(ToJson)

    平台用户。
    impl FromJson for User

    User::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露，避免工具链的 「隐式提升为方法」弃用告警。

    User::to_json

    source
    fn User::to_json(User) -> Json

    显式声明 derive 出来的 ToJson 实现以普通方法暴露（管理端建/改用户时要回传）。

    UserResponse

    source
    pub struct UserResponse {
      user : User
      otp : Bool
    }

    GET /api/me 的响应：用户信息，外加该账号是否开启两步验证。

    Go 服务端把 model.User 内嵌进这个结构体，两组字段在 JSON 里是同一层。 MoonBit 没有结构体内嵌，所以这里用 user 字段承载用户信息——解码时仍是 从同一个扁平对象里读。

    UserResponse::from_json

    source

    显式声明手写的 FromJson 实现以普通方法暴露。

    array_field

    source
    fn[T : 
    FromJson    ] array_field(fields : Map[String, Json], key : String) -> Array[T]

    数组字段；缺失或 null 时给空数组。

    Go 会把值为 nil 的切片序列化成 null（而不是 []），所以模型里的 列表字段一律走这里，用户拿到的永远是数组、不用处理 null。

    bool_field

    source
    fn bool_field(fields : Map[String, Json], key : String) -> Bool

    布尔字段，缺失时给 false。

    bytes_reader

    source
    fn bytes_reader(data : Bytes) -> &
    Reader

    把一段内存里的字节包装成可读流。

    上传大文件时不要用它把整个文件读进内存，而是自己打开文件拿到 Reader 交给 FileSystem::put；这个助手更适合「手里已经有一块字节」的场景 （分片上传的每一片、表单里的小文件）。

    decode_data

    source
    fn[T : 
    FromJson    ] decode_data(json : Json) -> T raise OpenListError

    把统一信封里的 data 解码成目标类型（解码前先剔除 null 字段）。

    解码失败会抛 OpenListError::Decode，其中带上 core json 给出的 字段路径与原因，便于定位是哪个接口的哪个字段与模型不符。

    double_field

    source
    fn double_field(fields : Map[String, Json], key : String) -> Double

    浮点字段（进度百分比这类），缺失时给 0。

    int64_field

    source
    fn int64_field(fields : Map[String, Json], key : String) -> Int64

    64 位整数字段（文件大小、分页总数这类），缺失时给 0。

    int64_from_json

    source
    fn int64_from_json(value : Json) -> Int64?

    把一个 JSON 值读成 Int64：接受数字（OpenList 的 int64 就是数字）， 也接受字符串形态（core json 的 Int64 表示法）。

    int_field

    source
    fn int_field(fields : Map[String, Json], key : String) -> Int

    32 位整数字段（role、order、type 这类小整数），缺失时给 0。

    json_field

    source
    fn[T : 
    FromJson    ] json_field(fields : Map[String, Json], key : String) -> T?

    读一个字段并按目标类型解码；字段缺失、显式 null 或类型不符时给 None。

    手写 FromJson 的模型用它读普通字段，避免为每个字段重复一遍 try/catch。

    map_field

    source
    fn[V : 
    FromJson    ] map_field(fields : Map[String, Json], key : String) -> Map[String, V]

    字符串映射字段（哈希值表这类）；缺失或 null 时给空映射。

    page_pairs

    source
    fn page_pairs(page? : Int, per_page? : Int) -> Array[(String, Json?)]

    分页参数的键值对：page 与 per_page，未提供的不会出现。

    服务端对分页参数很宽容（page < 1 视作 1、per_page < 1 视作不限）， 所以调用方不传就是「用服务端默认行为」。

    let query = @core.query_json(@core.page_pairs(page=1))
    // => {"page": 1}

    query_int

    source
    fn query_int(value : Int) -> Json

    整数查询参数的便捷写法（Json::number 收的是 Double）。

    query_json

    source
    fn query_json(pairs : Array[(String, Json?)]) -> Json

    把 键 -> 可选值 列表变成查询参数对象。

    let query = @core.query_json([
      ("page", Some(Json::number(1))),
      ("path", Some(Json::string("/docs"))),
      ("refresh", None),
    ])
    // => {"page": 1, "path": "/docs"}

    query_string

    source
    fn query_string(value : String) -> Json

    字符串查询参数的便捷写法。

    string_field

    source
    fn string_field(fields : Map[String, Json], key : String) -> String

    字符串字段，缺失时给空串。

    strip_nulls

    source
    fn strip_nulls(json : Json) -> Json

    递归剔除 JSON 对象里值为 null 的字段；数组元素原样保留但会递归处理。

    uint_field

    source
    fn uint_field(fields : Map[String, Json], key : String) -> UInt

    32 位无符号整数字段（各类 ID），缺失时给 0。

    url_path_encode

    source
    fn url_path_encode(path : String) -> String

    对路径做百分号编码（RFC 3986，空格是 %20）。

    OpenList 的 File-Path 请求头要求路径是 URL 编码过的（服务端做 url.PathUnescape）。注意不能用 form 风格编码：PathUnescape 不会把 + 还原成空格，那样文件名里的空格会变成字面量加号。

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io