Dagger TypeScript SDK 指南EngineCacheEntrySet 缓存条目集 API 详解【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本篇技术指南以 Dagger 仓库docs/versioned_docs/version-0.19下的 TypeScript API 参考文档为主体系统讲解EngineCacheEntrySet引擎缓存条目集类的构造方式、四个核心方法及其配套的类型别名EngineCacheEntrySetID、EngineCacheEntrySetOpts并结合仓库源码core/schema/engine.go 与 sdk/typescript/src/api/client.gen.ts说明其底层调用链。读完本文你将掌握如何在 TypeScript 中通过dagger.engineCache().entrySet()查询 Dagger 引擎缓存占用逐条枚举缓存条目并理解该方法在引擎侧的解析逻辑与安全约束。类概览什么是 EngineCacheEntrySet根据官方 API 文档的定义EngineCacheEntrySet是A set of cache entries returned by a query to a cache即一次缓存查询所返回的一组缓存条目。它由EngineCache.entrySet()方法产生详见 EngineCache 类文档用来聚合描述引擎本地缓存当前的状态——包括占用空间总量、条目数量以及每个独立条目的明细。从类的继承关系看EngineCacheEntrySet直接继承自BaseClient这意味着它复用 Dagger TypeScript SDK 的统一客户端上下文Context所有查询字段的取值都通过内部 GraphQL 客户端按需执行lazy evaluation。在 GraphQL 层EngineCacheEntrySet实现了Node接口对应的类型定义位于 core/schema/testdata/base_schema.graphqlstype EngineCacheEntrySet implements Node { The total disk space used by the cache entries in this set. diskSpaceBytes: Int! The list of individual cache entries in the set entries: [EngineCacheEntry!]! The number of cache entries in this set. entryCount: Int! A unique identifier for this EngineCacheEntrySet. id: ID! }这 4 个字段与 TypeScript 类的 4 个公开方法一一对应是理解该类的最小信息面。构造函数仅供内部使用文档明确指出该构造函数仅限 SDK 内部使用不要在业务代码中手动new EngineCacheEntrySet(...)new EngineCacheEntrySet( ctx?: Context, _id?: EngineCacheEntrySetID, _diskSpaceBytes?: number, _entryCount?: number, ): EngineCacheEntrySet参数ctx为客户端上下文_id、_diskSpaceBytes、_entryCount均为带下划线前缀的私有字段由 Dagger 引擎返回结果时填充。对应的 TypeScript 生成代码见 sdk/typescript/src/api/client.gen.tsexport class EngineCacheEntrySet extends BaseClient { private readonly _id?: ID undefined private readonly _diskSpaceBytes?: number undefined private readonly _entryCount?: number undefined constructor( ctx?: Context, _id?: ID, _diskSpaceBytes?: number, _entryCount?: number, ) { super(ctx) this._id _id this._diskSpaceBytes _diskSpaceBytes this._entryCount _entryCount } // ... }一个值得注意的实现细节是diskSpaceBytes与entryCount方法在取值时会优先返回构造时已缓存的本地字段仅当字段未填充时才向引擎发起 GraphQL 查询见 client.gen.ts 中if (this._diskSpaceBytes)、if (this._entryCount)的短路逻辑。因此在一次 GraphQL 响应内已携带的聚合数据不会产生额外往返。公开方法详解id()获取唯一标识符id(): PromiseEngineCacheEntrySetID返回该EngineCacheEntrySet的唯一标识符。文档描述为A unique identifier for this EngineCacheEntrySet.其类型EngineCacheEntrySetID定义于 type-aliases/EngineCacheEntrySetID.mdtype EngineCacheEntrySetID string { __EngineCacheEntrySetID: never }这是一个品牌化字符串branded string类型底层是字符串但通过交叉一个永不为真的__EngineCacheEntrySetID: never字段形成名义类型防止与其他 ID 类型混用。该 ID 可通过 GraphQL 的loadEngineCacheEntrySetFromID(id: EngineCacheEntrySetID!): EngineCacheEntrySet!重新加载对象见 base_schema.graphqls。在生成代码中id()会选择 GraphQL 字段id并执行查询client.gen.tsid async (): PromiseID { if (this._id) { return this._id } const ctx this._ctx.select(id) const response: AwaitedID await ctx.execute() return response }diskSpaceBytes()查询集合总占用diskSpaceBytes(): Promisenumber返回该集合内所有缓存条目占用的总磁盘空间字节对应 GraphQL 字段diskSpaceBytes: Int!在 Go 引擎侧由EngineCacheEntrySet.DiskSpaceBytes字段承载。典型用途是评估引擎本地缓存的体积配合EngineCache.maxUsedSpace()/EngineCache.minFreeSpace()见 EngineCache 类文档判断缓存策略是否健康。entryCount()查询条目数量entryCount(): Promisenumber返回该集合中缓存条目的数量对应 GraphQL 字段entryCount: Int!。它与diskSpaceBytes()的组合可以计算平均条目占用辅助判断是否存在体积异常巨大的缓存条目。entries()枚举所有缓存条目entries(): PromiseEngineCacheEntry[]返回该集合中所有独立缓存条目的列表每个元素是EngineCacheEntry对象。EngineCacheEntry类文档见 classes/EngineCacheEntry.md其自身提供以下查询方法方法返回类型语义activelyUsed()Promiseboolean该条目是否正在被使用createdTimeUnixNano()Promisenumber条目的创建时间Unix 纳秒description()Promisestring条目的描述信息diskSpaceBytes()Promisenumber该条目占用的磁盘空间字节id()PromiseEngineCacheEntryID该条目的唯一标识符mostRecentUseTimeUnixNano()Promisenumber条目的最近使用时间Unix 纳秒entries()的生成代码展示了 SDK 的惰性查询模式client.gen.ts先选择entries字段并附带id子选择待执行返回 ID 列表后再通过new EngineCacheEntry(ctx.copy().selectNode(r.id, EngineCacheEntry))为每个 ID 重建客户端节点供后续按需调用各属性方法entries async (): PromiseEngineCacheEntry[] { const ctx this._ctx.select(entries).select(id) const response: Awaitedentries[] await ctx.execute() return response.map( (r) new EngineCacheEntry(ctx.copy().selectNode(r.id, EngineCacheEntry)), ) }而 Go 引擎侧entries解析器只是直接返回父对象中已加载的条目列表core/schema/engine.gofunc (s *engineSchema) cacheEntrySetEntries(ctx context.Context, parent *core.EngineCacheEntrySet, args struct{}) (dagql.Array[*core.EngineCacheEntry], error) { return parent.EntriesList, nil }配套类型别名EngineCacheEntrySetOptsEngineCacheEntrySetOpts是EngineCache.entrySet()的选项对象type-aliases/EngineCacheEntrySetOpts.md目前仅含一个可选属性type EngineCacheEntrySetOpts { key?: string }key用于按缓存键过滤条目集。在 Go 引擎的cacheEntrySet解析器中core/schema/engine.gokey的默认值为空字符串default:其处理逻辑分两支key 为空未指定引擎会生成一个全新的随机identity.NewID()作为查询键此时返回的是当前查询对应的空条目集占位对象通过srv.Select将EngineCache.entrySet(key: ...)下发给底层服务即该集合不代表任何真实缓存内容key 非空调用query.EngineLocalCacheEntries(ctx)从引擎本地缓存加载真实条目并包装为EngineCacheEntrySet返回。GraphQL 侧的字段声明为entrySet(key: String ): EngineCacheEntrySet!见 base_schema.graphqls与 Go 的default:标签一致。从源码看调用链与权限约束EngineCacheEntrySet并不是独立创建的对象其完整调用链为TypeScript: dagger.engineCache().entrySet({ key }) → GraphQL: engineCache { entrySet(key: String ) { id diskSpaceBytes entryCount entries { ... } } } → Go: engineSchema.cacheEntrySet (core/schema/engine.go#L106) → 引擎本地缓存: EngineLocalCacheEntries (core.EngineCacheEntrySet)两个关键安全约束值得注意cacheEntrySet与cachePrune一样都会先调用query.RequireMainClient(ctx)engine.go。这意味着读取缓存条目集要求当前会话是主客户端main client普通模块或子会话不能直接枚举引擎缓存防止缓存信息泄露或误操作。entries的解析不触发新的缓存扫描直接返回parent.EntriesListengine.go说明引擎在创建条目集时已经完成一次快照entries()读取的是快照数据。另外测试侧对同一类型的封装可见于 core/schema/test_server_test.goEngineLocalCacheEntries返回*core.EngineCacheEntrySetPruneEngineLocalCacheEntries则在裁剪后返回新的条目集——这说明该类型同时服务于查询缓存状态与裁剪后复查两个场景与EngineCache.prune()见 EngineCache 类文档构成完整的缓存治理闭环。实践一个完整的 TypeScript 用法示例基于上述 API可以编写一个完整的缓存状态检查脚本需要dagger.io/dagger客户端已连接引擎且会话为主客户端import { connect } from dagger.io/dagger connect(async (client) { // 1. 通过 engineCache().entrySet() 获取当前缓存条目集 // 不传 key 时返回的集合由引擎按当前查询上下文生成 const cache client.engineCache() const entrySet cache.entrySet() // 2. 查询集合级聚合指标 const totalBytes await entrySet.diskSpaceBytes() const count await entrySet.entryCount() console.log(cache entries: ${count}, total disk: ${totalBytes} bytes) // 3. 遍历每条缓存条目输出明细 const entries await entrySet.entries() for (const entry of entries) { const id await entry.id() const bytes await entry.diskSpaceBytes() const active await entry.activelyUsed() const created await entry.createdTimeUnixNano() const lastUsed await entry.mostRecentUseTimeUnixNano() console.log({ id, bytes, active, created: new Date(created / 1e6).toISOString(), lastUsed: new Date(lastUsed / 1e6).toISOString(), }) } })要点说明条目级字段创建时间、最近使用时间以Unix 纳秒为单位createdTimeUnixNano、mostRecentUseTimeUnixNano转毫秒需除以1e6才能用于Dateid()返回的是品牌化 ID 类型EngineCacheEntrySetID/EngineCacheEntryID可用作后续 GraphQLloadEngineCacheEntrySetFromID的入参实现跨会话恢复由于方法返回 Promise建议在connect回调中组合使用await或Promise.all控制并发。相关 API 导航围绕EngineCacheEntrySet以下几个文档与源码可作为继续深入的路标EngineCache 类文档entrySet()的宿主类型同时提供prune()、maxUsedSpace()、minFreeSpace()、reservedSpace()、targetSpace()等缓存治理方法EngineCacheEntry 类文档条目明细对象的字段与方法EngineCacheEntrySetID 类型文档 与 EngineCacheEntrySetOpts 类型文档配套类型定义GraphQL 类型定义与 ID 加载入口base_schema.graphqlsGo 引擎解析器实现core/schema/engine.goTypeScript SDK 生成代码sdk/typescript/src/api/client.gen.ts。EngineCacheEntrySet是 Dagger 引擎缓存观测与治理链路中的核心数据载体通过entrySet获取聚合快照用diskSpaceBytes()、entryCount()评估缓存体积用entries()逐条审视缓存内容再配合EngineCache.prune()完成释放——这套 API 组合足以支撑缓存体检、容量告警与定向清理等自动化运维场景。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Dagger TypeScript SDK 指南：EngineCacheEntrySet 缓存条目集 API 详解
Dagger TypeScript SDK 指南EngineCacheEntrySet 缓存条目集 API 详解【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本篇技术指南以 Dagger 仓库docs/versioned_docs/version-0.19下的 TypeScript API 参考文档为主体系统讲解EngineCacheEntrySet引擎缓存条目集类的构造方式、四个核心方法及其配套的类型别名EngineCacheEntrySetID、EngineCacheEntrySetOpts并结合仓库源码core/schema/engine.go 与 sdk/typescript/src/api/client.gen.ts说明其底层调用链。读完本文你将掌握如何在 TypeScript 中通过dagger.engineCache().entrySet()查询 Dagger 引擎缓存占用逐条枚举缓存条目并理解该方法在引擎侧的解析逻辑与安全约束。类概览什么是 EngineCacheEntrySet根据官方 API 文档的定义EngineCacheEntrySet是A set of cache entries returned by a query to a cache即一次缓存查询所返回的一组缓存条目。它由EngineCache.entrySet()方法产生详见 EngineCache 类文档用来聚合描述引擎本地缓存当前的状态——包括占用空间总量、条目数量以及每个独立条目的明细。从类的继承关系看EngineCacheEntrySet直接继承自BaseClient这意味着它复用 Dagger TypeScript SDK 的统一客户端上下文Context所有查询字段的取值都通过内部 GraphQL 客户端按需执行lazy evaluation。在 GraphQL 层EngineCacheEntrySet实现了Node接口对应的类型定义位于 core/schema/testdata/base_schema.graphqlstype EngineCacheEntrySet implements Node { The total disk space used by the cache entries in this set. diskSpaceBytes: Int! The list of individual cache entries in the set entries: [EngineCacheEntry!]! The number of cache entries in this set. entryCount: Int! A unique identifier for this EngineCacheEntrySet. id: ID! }这 4 个字段与 TypeScript 类的 4 个公开方法一一对应是理解该类的最小信息面。构造函数仅供内部使用文档明确指出该构造函数仅限 SDK 内部使用不要在业务代码中手动new EngineCacheEntrySet(...)new EngineCacheEntrySet( ctx?: Context, _id?: EngineCacheEntrySetID, _diskSpaceBytes?: number, _entryCount?: number, ): EngineCacheEntrySet参数ctx为客户端上下文_id、_diskSpaceBytes、_entryCount均为带下划线前缀的私有字段由 Dagger 引擎返回结果时填充。对应的 TypeScript 生成代码见 sdk/typescript/src/api/client.gen.tsexport class EngineCacheEntrySet extends BaseClient { private readonly _id?: ID undefined private readonly _diskSpaceBytes?: number undefined private readonly _entryCount?: number undefined constructor( ctx?: Context, _id?: ID, _diskSpaceBytes?: number, _entryCount?: number, ) { super(ctx) this._id _id this._diskSpaceBytes _diskSpaceBytes this._entryCount _entryCount } // ... }一个值得注意的实现细节是diskSpaceBytes与entryCount方法在取值时会优先返回构造时已缓存的本地字段仅当字段未填充时才向引擎发起 GraphQL 查询见 client.gen.ts 中if (this._diskSpaceBytes)、if (this._entryCount)的短路逻辑。因此在一次 GraphQL 响应内已携带的聚合数据不会产生额外往返。公开方法详解id()获取唯一标识符id(): PromiseEngineCacheEntrySetID返回该EngineCacheEntrySet的唯一标识符。文档描述为A unique identifier for this EngineCacheEntrySet.其类型EngineCacheEntrySetID定义于 type-aliases/EngineCacheEntrySetID.mdtype EngineCacheEntrySetID string { __EngineCacheEntrySetID: never }这是一个品牌化字符串branded string类型底层是字符串但通过交叉一个永不为真的__EngineCacheEntrySetID: never字段形成名义类型防止与其他 ID 类型混用。该 ID 可通过 GraphQL 的loadEngineCacheEntrySetFromID(id: EngineCacheEntrySetID!): EngineCacheEntrySet!重新加载对象见 base_schema.graphqls。在生成代码中id()会选择 GraphQL 字段id并执行查询client.gen.tsid async (): PromiseID { if (this._id) { return this._id } const ctx this._ctx.select(id) const response: AwaitedID await ctx.execute() return response }diskSpaceBytes()查询集合总占用diskSpaceBytes(): Promisenumber返回该集合内所有缓存条目占用的总磁盘空间字节对应 GraphQL 字段diskSpaceBytes: Int!在 Go 引擎侧由EngineCacheEntrySet.DiskSpaceBytes字段承载。典型用途是评估引擎本地缓存的体积配合EngineCache.maxUsedSpace()/EngineCache.minFreeSpace()见 EngineCache 类文档判断缓存策略是否健康。entryCount()查询条目数量entryCount(): Promisenumber返回该集合中缓存条目的数量对应 GraphQL 字段entryCount: Int!。它与diskSpaceBytes()的组合可以计算平均条目占用辅助判断是否存在体积异常巨大的缓存条目。entries()枚举所有缓存条目entries(): PromiseEngineCacheEntry[]返回该集合中所有独立缓存条目的列表每个元素是EngineCacheEntry对象。EngineCacheEntry类文档见 classes/EngineCacheEntry.md其自身提供以下查询方法方法返回类型语义activelyUsed()Promiseboolean该条目是否正在被使用createdTimeUnixNano()Promisenumber条目的创建时间Unix 纳秒description()Promisestring条目的描述信息diskSpaceBytes()Promisenumber该条目占用的磁盘空间字节id()PromiseEngineCacheEntryID该条目的唯一标识符mostRecentUseTimeUnixNano()Promisenumber条目的最近使用时间Unix 纳秒entries()的生成代码展示了 SDK 的惰性查询模式client.gen.ts先选择entries字段并附带id子选择待执行返回 ID 列表后再通过new EngineCacheEntry(ctx.copy().selectNode(r.id, EngineCacheEntry))为每个 ID 重建客户端节点供后续按需调用各属性方法entries async (): PromiseEngineCacheEntry[] { const ctx this._ctx.select(entries).select(id) const response: Awaitedentries[] await ctx.execute() return response.map( (r) new EngineCacheEntry(ctx.copy().selectNode(r.id, EngineCacheEntry)), ) }而 Go 引擎侧entries解析器只是直接返回父对象中已加载的条目列表core/schema/engine.gofunc (s *engineSchema) cacheEntrySetEntries(ctx context.Context, parent *core.EngineCacheEntrySet, args struct{}) (dagql.Array[*core.EngineCacheEntry], error) { return parent.EntriesList, nil }配套类型别名EngineCacheEntrySetOptsEngineCacheEntrySetOpts是EngineCache.entrySet()的选项对象type-aliases/EngineCacheEntrySetOpts.md目前仅含一个可选属性type EngineCacheEntrySetOpts { key?: string }key用于按缓存键过滤条目集。在 Go 引擎的cacheEntrySet解析器中core/schema/engine.gokey的默认值为空字符串default:其处理逻辑分两支key 为空未指定引擎会生成一个全新的随机identity.NewID()作为查询键此时返回的是当前查询对应的空条目集占位对象通过srv.Select将EngineCache.entrySet(key: ...)下发给底层服务即该集合不代表任何真实缓存内容key 非空调用query.EngineLocalCacheEntries(ctx)从引擎本地缓存加载真实条目并包装为EngineCacheEntrySet返回。GraphQL 侧的字段声明为entrySet(key: String ): EngineCacheEntrySet!见 base_schema.graphqls与 Go 的default:标签一致。从源码看调用链与权限约束EngineCacheEntrySet并不是独立创建的对象其完整调用链为TypeScript: dagger.engineCache().entrySet({ key }) → GraphQL: engineCache { entrySet(key: String ) { id diskSpaceBytes entryCount entries { ... } } } → Go: engineSchema.cacheEntrySet (core/schema/engine.go#L106) → 引擎本地缓存: EngineLocalCacheEntries (core.EngineCacheEntrySet)两个关键安全约束值得注意cacheEntrySet与cachePrune一样都会先调用query.RequireMainClient(ctx)engine.go。这意味着读取缓存条目集要求当前会话是主客户端main client普通模块或子会话不能直接枚举引擎缓存防止缓存信息泄露或误操作。entries的解析不触发新的缓存扫描直接返回parent.EntriesListengine.go说明引擎在创建条目集时已经完成一次快照entries()读取的是快照数据。另外测试侧对同一类型的封装可见于 core/schema/test_server_test.goEngineLocalCacheEntries返回*core.EngineCacheEntrySetPruneEngineLocalCacheEntries则在裁剪后返回新的条目集——这说明该类型同时服务于查询缓存状态与裁剪后复查两个场景与EngineCache.prune()见 EngineCache 类文档构成完整的缓存治理闭环。实践一个完整的 TypeScript 用法示例基于上述 API可以编写一个完整的缓存状态检查脚本需要dagger.io/dagger客户端已连接引擎且会话为主客户端import { connect } from dagger.io/dagger connect(async (client) { // 1. 通过 engineCache().entrySet() 获取当前缓存条目集 // 不传 key 时返回的集合由引擎按当前查询上下文生成 const cache client.engineCache() const entrySet cache.entrySet() // 2. 查询集合级聚合指标 const totalBytes await entrySet.diskSpaceBytes() const count await entrySet.entryCount() console.log(cache entries: ${count}, total disk: ${totalBytes} bytes) // 3. 遍历每条缓存条目输出明细 const entries await entrySet.entries() for (const entry of entries) { const id await entry.id() const bytes await entry.diskSpaceBytes() const active await entry.activelyUsed() const created await entry.createdTimeUnixNano() const lastUsed await entry.mostRecentUseTimeUnixNano() console.log({ id, bytes, active, created: new Date(created / 1e6).toISOString(), lastUsed: new Date(lastUsed / 1e6).toISOString(), }) } })要点说明条目级字段创建时间、最近使用时间以Unix 纳秒为单位createdTimeUnixNano、mostRecentUseTimeUnixNano转毫秒需除以1e6才能用于Dateid()返回的是品牌化 ID 类型EngineCacheEntrySetID/EngineCacheEntryID可用作后续 GraphQLloadEngineCacheEntrySetFromID的入参实现跨会话恢复由于方法返回 Promise建议在connect回调中组合使用await或Promise.all控制并发。相关 API 导航围绕EngineCacheEntrySet以下几个文档与源码可作为继续深入的路标EngineCache 类文档entrySet()的宿主类型同时提供prune()、maxUsedSpace()、minFreeSpace()、reservedSpace()、targetSpace()等缓存治理方法EngineCacheEntry 类文档条目明细对象的字段与方法EngineCacheEntrySetID 类型文档 与 EngineCacheEntrySetOpts 类型文档配套类型定义GraphQL 类型定义与 ID 加载入口base_schema.graphqlsGo 引擎解析器实现core/schema/engine.goTypeScript SDK 生成代码sdk/typescript/src/api/client.gen.ts。EngineCacheEntrySet是 Dagger 引擎缓存观测与治理链路中的核心数据载体通过entrySet获取聚合快照用diskSpaceBytes()、entryCount()评估缓存体积用entries()逐条审视缓存内容再配合EngineCache.prune()完成释放——这套 API 组合足以支撑缓存体检、容量告警与定向清理等自动化运维场景。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考