` 与 `/df` 接口深度解析)
Puter 云存储容量与用量查询puter.fs.space()与/df接口深度解析【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本篇围绕 Puter 文件系统 API 的puter.fs.space()方法展开它用于查询当前用户在整个 Puter 云盘上获得的存储总容量capacity与已用量used。本文以官方文档 space.md 为核心骨架结合 puter-js SDK 与后端 LegacyFSController 的源码实现讲清楚调用约定、返回值含义、权限与限流约束并给出可运行的浏览器与 Node.js 示例以及把配额检查接入上传流程的实战思路。方法概览与文档定位puter.fs.space()是 Puter 云文件系统Cloud StorageAPI 家族中的磁盘配额查询操作对应类 Unix 系统中dfdisk free的语义因此在 官方文档 中其功能描述为返回当前用户的存储空间容量与用量。它不需要任何路径参数作用对象是整个用户云盘而非某个具体目录。在文档首页的 YAML front matter 中该方法的正式标题为puter.fs.space()简介为Check how much storage capacity the user has and how much they have used——即你既可以用它向用户展示云盘总容量/剩余空间也可以在业务逻辑中判断剩余配额是否足以完成后续写入。语法puter.fs.space()参数无。调用时不需要传入路径、文件或任何配置项。返回值返回一个Promiseresolve 后得到一个包含以下两个数值属性的对象属性类型含义capacityNumber用户可用的存储总容量单位字节bytesusedNumber用户已使用的存储空间单位字节bytes由此可以很容易推导出剩余可用空间const free capacity - used;SDK 中对这两个字段的类型定义位于 src/puter-js/src/modules/FileSystem/types.js/** * Storage space information for the current user, in bytes. * * typedef {Object} SpaceInfo * property {number} capacity Total storage capacity available to the user, in bytes. * property {number} used Amount of storage space used by the user, in bytes. */注意这里的类型文件是 JSDoc-only 的共享形状声明Shapes shared across theputer.fsoperations运行时并不导出真正暴露给调用者的是下文要讲的space操作实现。官方文档示例浏览器控制台查看配额space.md 给出了一个完整的 HTML 示例通过加载https://js.puter.com/v2/的 SDK然后调用puter.space()将结果打印到浏览器控制台。html body script srchttps://js.puter.com/v2//script script // Retrieves the storage space capacity and usage for the current user, and prints them to the browser console puter.space().then((space){ console.log(space) }); /script /body /html运行后控制台会输出形如下面的对象{ capacity: 1073741824, used: 268435456 }关于示例中有两点值得说明示例中使用的是早期/顶层写法puter.space()在当前 v2 模块化 SDK 中该操作被组织在文件系统模块下规范写法是puter.fs.space()见 src/puter-js/src/modules/FileSystem/index.js 的导入与 L46 的模块成员绑定space space;。二者路由到同一份底层实现。console.log打印的是完整对象如果你只关心剩余空间可以解构capacity与used后计算差值。权限要求未授权时返回错误文档在方法说明下方用 info 提示框特别强调了一条约束This method requires permission to access the users storage space. If the user has not granted permission, the method will return an error.也就是说space()不是匿名可调的接口它要求访问用户存储空间的授权。落到实现层可以拆成两道闸门SDK 侧认证闸门所有文件系统操作在发请求前都会先经过ensureAuthenticated()——若当前puter.authToken为空且运行在 Web 环境会先尝试拉起 Puter 登录/授权puter.ui.authenticateWithPuter()认证失败时方法以Authentication failed.拒绝见 scaffold.js 与 L114-L123。服务端 actor 闸门后端/df处理器第一行就是this.#requireActor(req)没有合法用户身份的请求会被拒绝对应的测试用例也专门覆盖了该 actor gate见 LegacyFSController.test.ts。因此在浏览器控制台直接运行示例前请确保 SDK 已拿到有效的登录态通常由 SDK 在页面内完成 OAuth/登录跳转否则会收到错误而拿不到配额数据。SDK 源码一个最小的请求型操作在 puter-js 仓库中space的实现是整个文件系统操作集中最简洁的范例之一。完整源码见 src/puter-js/src/modules/FileSystem/operations/space.jsimport { defineOperation } from ./scaffold.js; /** typedef {import(../types.js).SpaceInfo} SpaceInfo */ /** typedef {import(../../../lib/types.js).RequestCallbacksSpaceInfo} SpaceCallbacks */ /** * Returns the storage capacity and usage of the current user, in bytes. * * type {{ * (options?: SpaceCallbacks): PromiseSpaceInfo, * ( * success: (value: SpaceInfo) void, * error?: (reason: unknown) void, * ): PromiseSpaceInfo, * }} */ const space defineOperation({ request () { return { endpoint: /df }; }, }); export default space;这段代码揭示了几条实现事实底层走/df接口space的请求规格只有一行——{ endpoint: /df }。方法名space()只是 SDK 对服务端df语义的友好封装。统一脚手架defineOperation定义于 scaffold.js负责一切通用逻辑——解析参数、认证闸门、发送 XHR、Promise/回调双风格结果投递。因此space天然支持选项对象式与旧式回调式两种调用约定。Promise 与回调并存从 JSDoc 的 overload 可以看到space()既可以await得到SpaceInfo也可以传入success/error回调。底层fsRequest会保证 Promise 与回调拿到同一份结果见 scaffold.js 中transform 必须先于回调执行的注释约定。defineOperation接收请求后会把请求交给fsRequest默认使用POST方法、携带认证头向this.APIOrigin endpoint发起请求并将响应体原样作为结果 resolve——因为/df返回的就是{ used, capacity }无需 transform所以响应对象与文档描述的返回值字段一一对应。后端/df配额从哪来前端把请求发到/df后由后端 LegacyFSController 处理。在 src/backend/controllers/fs/LegacyFSController.ts 中路由注册如下router.all(/df, { ...apiOptions, rateLimit: FS_DF_LIMIT }, this.df);处理器实现见 LegacyFSController.ts/** GET|POST /df — user storage allowance. */ df async (req: Request, res: Response): Promisevoid { this.#requireActor(req); const userId this.#getActorUserId(req); const allowance await this.services.fs.getUsersStorageAllowance(userId); res.json({ used: allowance.curr, capacity: allowance.max, }); };后端视角的几个关键点配额对象是存储许可storage allowancegetUsersStorageAllowance(userId)为用户返回一个许可结构其中curr是当前已用额度max是额度上限分别被映射为响应中的used与capacity。也就是说capacity并不是物理磁盘总量而是服务端为该用户/账户配置的可用配额上限它会随账户套餐、管理员配置等因素变化。GET 与 POST 均可路由用router.all(/df, ...)注册两种 HTTP 方法都会被接受SDK 侧默认走 POST。用户级限流/df使用了FS_DF_LIMIT做速率限制。其定义为userWindow(fs:df, 60, 30, 15)见 limits.ts即以用户为维度、以 60 秒为窗口对fs:df键统计请求频率相关窗口/限流行为在 limits.test.ts 附近有测试覆盖。这提醒开发者不要把space()放进高频轮询循环必要时在本地缓存结果并定时刷新。配套测试印证的行为后端测试 LegacyFSController.test.ts 对df的核心断言是新用户fresh user的used为 0而capacity大于 0。这与文档语义完全一致未上传任何文件时used 0但用户始终拥有一个正数的配额上限。你可以在自己的应用中把used 0作为全新账号的弱信号如需更强信号建议配合readdir根目录结果判断。实战用space()做上传前的配额预检space()最典型的实战用途是写入前的配额预检。有意思的是put-js 自己在upload流程里就内置了这样一道检查。在 upload/index.js 中// we want to avoid uploading files in case there is not enough storage space. // the user uploads a very large folder/file and then the server rejects it because there is not enough space ... storage await this.space(); if ( ... storage 不足 ... ) { return error({ code: NOT_ENOUGH_SPACE, message: Not enough storage space available. }); }即 SDK 官方上传实现会先调用this.space()读取配额估算待上传文件总大小若空间不足则在本地提前以NOT_ENOUGH_SPACE拒绝避免把明知会失败的大文件白白推到服务器。对应地其它存储操作copy、mkdir 等在服务端返回 413 配额拒绝时SDK 会在 reject 路径上调用promptIfStorageLimitError见 scaffold.js引导用户处理容量问题其实现位于 storageLimitPrompt.js。基于同样思路你自己的应用也可以写出如下通用工具函数// 检查剩余空间是否足够容纳 size 字节的写入 async function ensureSpaceAvailable(size, puter) { const { capacity, used } await puter.fs.space(); const free capacity - used; if (free size) { throw new Error( Not enough space: need ${size} bytes but only ${free} bytes free ); } return { capacity, used, free }; }一个完整的 Node.jsESM示例import * as puter from puter; // 假设已通过 puter.auth / 环境变量完成身份初始化 const { capacity, used } await puter.fs.space(); console.log(已用 ${used} 字节总计 ${capacity} 字节); console.log(剩余 ${capacity - used} 字节);常见问题与注意事项单位是字节bytescapacity与used均以字节计展示给人看时需要自行换算如used / 1024 / 1024 / 1024得 GiBSDK 不做格式化。必须处于已授权状态未登录或未授予存储访问权限时方法会返回错误见上文权限要求一节文档 info 框与后端 actor gate 双重确认了这一约束。不要高频轮询/df存在用户级速率限制fs:df键60 秒窗口见 limits.ts应缓存结果、在关键动作前再刷新。capacity是配额而非物理容量它由服务端为用户配置的存储许可决定随套餐/管理员策略变化自托管部署中具体的配额策略由各data/subPolicies策略文件与服务端存储逻辑共同决定前端不应硬编码假设其值。无需路径参数space()不接收任何参数也不针对目录计算——目录级容量统计并不在该方法职责内。延伸阅读方法官方文档src/docs/src/FS/space.mdFS API 的聚合总览可看 src/docs/src/FS.md。SDK 操作实现space.js、scaffold.js模块装配见 FileSystem/index.js。返回值类型定义FileSystem/types.js。后端接口LegacyFSController.ts 的df处理器、limits.ts 的限流配置及 LegacyFSController.test.ts 的测试。关联文档上传前配额预检见 upload 源码其余文件系统操作stat、readdir、write、mkdir等的官方说明位于 src/docs/src/FS/ 目录可与space()组合实现完整的云盘应用。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puter 云存储容量与用量查询puter.fs.space()与/df接口深度解析【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本篇围绕 Puter 文件系统 API 的puter.fs.space()方法展开它用于查询当前用户在整个 Puter 云盘上获得的存储总容量capacity与已用量used。本文以官方文档 space.md 为核心骨架结合 puter-js SDK 与后端 LegacyFSController 的源码实现讲清楚调用约定、返回值含义、权限与限流约束并给出可运行的浏览器与 Node.js 示例以及把配额检查接入上传流程的实战思路。方法概览与文档定位puter.fs.space()是 Puter 云文件系统Cloud StorageAPI 家族中的磁盘配额查询操作对应类 Unix 系统中dfdisk free的语义因此在 官方文档 中其功能描述为返回当前用户的存储空间容量与用量。它不需要任何路径参数作用对象是整个用户云盘而非某个具体目录。在文档首页的 YAML front matter 中该方法的正式标题为puter.fs.space()简介为Check how much storage capacity the user has and how much they have used——即你既可以用它向用户展示云盘总容量/剩余空间也可以在业务逻辑中判断剩余配额是否足以完成后续写入。语法puter.fs.space()参数无。调用时不需要传入路径、文件或任何配置项。返回值返回一个Promiseresolve 后得到一个包含以下两个数值属性的对象属性类型含义capacityNumber用户可用的存储总容量单位字节bytesusedNumber用户已使用的存储空间单位字节bytes由此可以很容易推导出剩余可用空间const free capacity - used;SDK 中对这两个字段的类型定义位于 src/puter-js/src/modules/FileSystem/types.js/** * Storage space information for the current user, in bytes. * * typedef {Object} SpaceInfo * property {number} capacity Total storage capacity available to the user, in bytes. * property {number} used Amount of storage space used by the user, in bytes. */注意这里的类型文件是 JSDoc-only 的共享形状声明Shapes shared across theputer.fsoperations运行时并不导出真正暴露给调用者的是下文要讲的space操作实现。官方文档示例浏览器控制台查看配额space.md 给出了一个完整的 HTML 示例通过加载https://js.puter.com/v2/的 SDK然后调用puter.space()将结果打印到浏览器控制台。html body script srchttps://js.puter.com/v2//script script // Retrieves the storage space capacity and usage for the current user, and prints them to the browser console puter.space().then((space){ console.log(space) }); /script /body /html运行后控制台会输出形如下面的对象{ capacity: 1073741824, used: 268435456 }关于示例中有两点值得说明示例中使用的是早期/顶层写法puter.space()在当前 v2 模块化 SDK 中该操作被组织在文件系统模块下规范写法是puter.fs.space()见 src/puter-js/src/modules/FileSystem/index.js 的导入与 L46 的模块成员绑定space space;。二者路由到同一份底层实现。console.log打印的是完整对象如果你只关心剩余空间可以解构capacity与used后计算差值。权限要求未授权时返回错误文档在方法说明下方用 info 提示框特别强调了一条约束This method requires permission to access the users storage space. If the user has not granted permission, the method will return an error.也就是说space()不是匿名可调的接口它要求访问用户存储空间的授权。落到实现层可以拆成两道闸门SDK 侧认证闸门所有文件系统操作在发请求前都会先经过ensureAuthenticated()——若当前puter.authToken为空且运行在 Web 环境会先尝试拉起 Puter 登录/授权puter.ui.authenticateWithPuter()认证失败时方法以Authentication failed.拒绝见 scaffold.js 与 L114-L123。服务端 actor 闸门后端/df处理器第一行就是this.#requireActor(req)没有合法用户身份的请求会被拒绝对应的测试用例也专门覆盖了该 actor gate见 LegacyFSController.test.ts。因此在浏览器控制台直接运行示例前请确保 SDK 已拿到有效的登录态通常由 SDK 在页面内完成 OAuth/登录跳转否则会收到错误而拿不到配额数据。SDK 源码一个最小的请求型操作在 puter-js 仓库中space的实现是整个文件系统操作集中最简洁的范例之一。完整源码见 src/puter-js/src/modules/FileSystem/operations/space.jsimport { defineOperation } from ./scaffold.js; /** typedef {import(../types.js).SpaceInfo} SpaceInfo */ /** typedef {import(../../../lib/types.js).RequestCallbacksSpaceInfo} SpaceCallbacks */ /** * Returns the storage capacity and usage of the current user, in bytes. * * type {{ * (options?: SpaceCallbacks): PromiseSpaceInfo, * ( * success: (value: SpaceInfo) void, * error?: (reason: unknown) void, * ): PromiseSpaceInfo, * }} */ const space defineOperation({ request () { return { endpoint: /df }; }, }); export default space;这段代码揭示了几条实现事实底层走/df接口space的请求规格只有一行——{ endpoint: /df }。方法名space()只是 SDK 对服务端df语义的友好封装。统一脚手架defineOperation定义于 scaffold.js负责一切通用逻辑——解析参数、认证闸门、发送 XHR、Promise/回调双风格结果投递。因此space天然支持选项对象式与旧式回调式两种调用约定。Promise 与回调并存从 JSDoc 的 overload 可以看到space()既可以await得到SpaceInfo也可以传入success/error回调。底层fsRequest会保证 Promise 与回调拿到同一份结果见 scaffold.js 中transform 必须先于回调执行的注释约定。defineOperation接收请求后会把请求交给fsRequest默认使用POST方法、携带认证头向this.APIOrigin endpoint发起请求并将响应体原样作为结果 resolve——因为/df返回的就是{ used, capacity }无需 transform所以响应对象与文档描述的返回值字段一一对应。后端/df配额从哪来前端把请求发到/df后由后端 LegacyFSController 处理。在 src/backend/controllers/fs/LegacyFSController.ts 中路由注册如下router.all(/df, { ...apiOptions, rateLimit: FS_DF_LIMIT }, this.df);处理器实现见 LegacyFSController.ts/** GET|POST /df — user storage allowance. */ df async (req: Request, res: Response): Promisevoid { this.#requireActor(req); const userId this.#getActorUserId(req); const allowance await this.services.fs.getUsersStorageAllowance(userId); res.json({ used: allowance.curr, capacity: allowance.max, }); };后端视角的几个关键点配额对象是存储许可storage allowancegetUsersStorageAllowance(userId)为用户返回一个许可结构其中curr是当前已用额度max是额度上限分别被映射为响应中的used与capacity。也就是说capacity并不是物理磁盘总量而是服务端为该用户/账户配置的可用配额上限它会随账户套餐、管理员配置等因素变化。GET 与 POST 均可路由用router.all(/df, ...)注册两种 HTTP 方法都会被接受SDK 侧默认走 POST。用户级限流/df使用了FS_DF_LIMIT做速率限制。其定义为userWindow(fs:df, 60, 30, 15)见 limits.ts即以用户为维度、以 60 秒为窗口对fs:df键统计请求频率相关窗口/限流行为在 limits.test.ts 附近有测试覆盖。这提醒开发者不要把space()放进高频轮询循环必要时在本地缓存结果并定时刷新。配套测试印证的行为后端测试 LegacyFSController.test.ts 对df的核心断言是新用户fresh user的used为 0而capacity大于 0。这与文档语义完全一致未上传任何文件时used 0但用户始终拥有一个正数的配额上限。你可以在自己的应用中把used 0作为全新账号的弱信号如需更强信号建议配合readdir根目录结果判断。实战用space()做上传前的配额预检space()最典型的实战用途是写入前的配额预检。有意思的是put-js 自己在upload流程里就内置了这样一道检查。在 upload/index.js 中// we want to avoid uploading files in case there is not enough storage space. // the user uploads a very large folder/file and then the server rejects it because there is not enough space ... storage await this.space(); if ( ... storage 不足 ... ) { return error({ code: NOT_ENOUGH_SPACE, message: Not enough storage space available. }); }即 SDK 官方上传实现会先调用this.space()读取配额估算待上传文件总大小若空间不足则在本地提前以NOT_ENOUGH_SPACE拒绝避免把明知会失败的大文件白白推到服务器。对应地其它存储操作copy、mkdir 等在服务端返回 413 配额拒绝时SDK 会在 reject 路径上调用promptIfStorageLimitError见 scaffold.js引导用户处理容量问题其实现位于 storageLimitPrompt.js。基于同样思路你自己的应用也可以写出如下通用工具函数// 检查剩余空间是否足够容纳 size 字节的写入 async function ensureSpaceAvailable(size, puter) { const { capacity, used } await puter.fs.space(); const free capacity - used; if (free size) { throw new Error( Not enough space: need ${size} bytes but only ${free} bytes free ); } return { capacity, used, free }; }一个完整的 Node.jsESM示例import * as puter from puter; // 假设已通过 puter.auth / 环境变量完成身份初始化 const { capacity, used } await puter.fs.space(); console.log(已用 ${used} 字节总计 ${capacity} 字节); console.log(剩余 ${capacity - used} 字节);常见问题与注意事项单位是字节bytescapacity与used均以字节计展示给人看时需要自行换算如used / 1024 / 1024 / 1024得 GiBSDK 不做格式化。必须处于已授权状态未登录或未授予存储访问权限时方法会返回错误见上文权限要求一节文档 info 框与后端 actor gate 双重确认了这一约束。不要高频轮询/df存在用户级速率限制fs:df键60 秒窗口见 limits.ts应缓存结果、在关键动作前再刷新。capacity是配额而非物理容量它由服务端为用户配置的存储许可决定随套餐/管理员策略变化自托管部署中具体的配额策略由各data/subPolicies策略文件与服务端存储逻辑共同决定前端不应硬编码假设其值。无需路径参数space()不接收任何参数也不针对目录计算——目录级容量统计并不在该方法职责内。延伸阅读方法官方文档src/docs/src/FS/space.mdFS API 的聚合总览可看 src/docs/src/FS.md。SDK 操作实现space.js、scaffold.js模块装配见 FileSystem/index.js。返回值类型定义FileSystem/types.js。后端接口LegacyFSController.ts 的df处理器、limits.ts 的限流配置及 LegacyFSController.test.ts 的测试。关联文档上传前配额预检见 upload 源码其余文件系统操作stat、readdir、write、mkdir等的官方说明位于 src/docs/src/FS/ 目录可与space()组合实现完整的云盘应用。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 热路径)
