Dagger TypeScript SDK 中 ContainerWithNewFileOpts 详解用 withNewFile 向容器写入文件【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerContainerWithNewFileOpts是 Dagger TypeScript SDKdagger.io/dagger中Container.withNewFile方法的可选参数类型。本文围绕该类型别名展开逐一剖析其expand、owner、permissions三个可选属性的语义与默认行为并结合 Dagger 仓库中core/schema/container.go与sdk/typescript/src/api/client.gen.ts的源码实现讲清环境变量展开、属主继承、权限落盘等底层机制最后给出可直接运行的实战示例。类型定义速览在 Dagger 的 TypeScript 客户端生成代码中ContainerWithNewFileOpts被定义为普通对象类型object所有属性均为可选项type ContainerWithNewFileOpts { /** * Replace ${VAR} or $VAR in the value of path according to the current * environment variables defined in the container (e.g. /$VAR/foo.txt). */ expand?: boolean /** * A user:group to set for the file. * The user and group can either be an ID (1000:1000) or a name (foo:bar). * If the group is omitted, it defaults to the same as the user. */ owner?: string /** * Permissions of the new file. Example: 0600 */ permissions?: number }该类型定义位于 docs/versioned_docs/version-0.20/reference/typescript/api/client.gen/type-aliases/ContainerWithNewFileOpts.md其内容由 SDK 代码生成器根据 GraphQL schema 自动产出。withNewFile方法本身在 sdk/typescript/src/api/client.gen.ts 中声明用于返回一个新的容器快照在其文件系统中以文本内容新增一个文件。与 withNewFile 的关系ContainerWithNewFileOpts是withNewFile的第三个参数withNewFile( path: string, contents: string, opts?: ContainerWithNewFileOpts, ): Container对应 GraphQL 层的参数结构在 core/schema/container.go 中定义这也是理解各选项默认值的最直接依据type containerWithNewFileArgs struct { Path string Contents string Permissions int default:0644 Owner string default: InheritOwner bool default:false Expand bool default:false }两个值得注意的事实Permissions的默认值是0644即所有者可读写、组和其他人只读即使不传permissions新建文件也拥有合理的安全权限Expand默认关闭路径中的$VAR不会被自动替换需要显式传入expand: true。此外服务端参数中还包含InheritOwner默认为false它对应 SDK 中withNewFile的 JSDoc 所描述的opts.inheritOwner——将文件属主设置为容器当前的用户。这与下文owner参数在语义上互补。属性逐一解析expand?: boolean —— 对路径做环境变量展开expand决定是否按照容器内当前定义的环境变量替换path参数中的${VAR}或$VAR。文档给出的示例是/$VAR/foo.txt当容器内存在名为VAR的环境变量时该路径会被展开为对应值。其底层实现在 core/schema/container.go 的expandEnvVar函数中关键逻辑为expanded : os.Expand(input, func(k string) string { // set error if its a secret env variable if slices.Contains(secretEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with secret env variable %q, k) return } if slices.Contains(volatileEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with volatile env variable %q, k) return } v, _ : core.LookupEnv(cfg.Env, k) return v })三点关键细节只针对路径展开作用域仅限于path参数不影响contents文件内容基于容器自身环境替换源是容器镜像配置cfg.Env中的环境变量而非宿主机或客户端进程的环境变量安全约束如果路径中引用的变量名是密钥环境变量secret或易变环境变量volatile envexpandEnvVar会直接返回错误拒绝展开。这是为了防止通过路径回显泄露敏感值。从源码结构看os.Expand同时支持$VAR与${VAR}两种语法与文档描述一致。owner?: string —— 设置文件属主owner指定新建文件的所有者格式为user:group。按文档说明用户与组可以是ID如1000:1000或名称如foo:bar组省略时只传1000或foo组默认与用户相同。服务端对属主的解析入口在 core/schema/container.go 的inheritedOwner函数注意它与inheritOwner的关系func inheritedOwner(parent dagql.ObjectResult[*core.Container], owner string, inheritOwner bool) (string, error) { if !inheritOwner { return owner, nil } if owner ! { return , errors.New(cannot set both owner and inheritOwner) } return parent.Self().Config.User, nil }由此可以得出两条行为准则owner与inheritOwner互斥同时设置会报错cannot set both owner and inheritOwner当inheritOwner: true时属主直接取父容器的Config.User即容器当前用户。permissions?: number —— 文件权限位permissions以数字形式给出新建文件的权限位文档示例为0600。结合服务端默认值可知未传时使用默认值0644传0表示不设置服务端仅在args.Permissions ! 0时才把权限附加到内部创建的file节点上见withNewFile实现。该值最终作用于通过内部file节点创建的文件对象并随文件一同写入容器文件系统。源码级实现流程withNewFile在 core/schema/container.go 中的执行链路大致如下路径预处理调用expandEnvVar依据Expand标志决定是否展开路径中的变量拆分文件名用filepath.Split(filepath.Clean(path))提取文件名并将其作为file节点的name与contents若权限非 0 则附带permissions克隆父容器调用cloneContainerForSchemaChild基于父容器复制文件系统、挂载点、元数据、镜像配置、环境变量等保证操作不可变immutable返回的是新容器快照解析属主通过inheritedOwner确定最终owner挂载懒状态构造core.ContainerWithFileLazy见 core/container.go把父容器 路径 文件源 属主记录为待求值lazy状态真正写入文件系统推迟到该容器被实际求值如执行export、file读取或运行容器时进行。这一设计保证了 Dagger 的延迟执行语义withNewFile本身只描述变更不触发任何 IO所有文件系统操作都发生在求值阶段。实战示例下面是一个完整的 TypeScript 示例综合使用三个选项import { connect } from dagger.io/dagger connect(async (client) { const ctr client .container() .from(alpine:latest) .withEnvVariable(APP_HOME, /srv/app) .withNewFile(/$APP_HOME/config/app.conf, log_level debug, { expand: true, // /$APP_HOME/config/app.conf - /srv/app/config/app.conf owner: 1000:1000, // 属主 user:group组省略时默认同 user permissions: 0o600, // 仅属主可读写 }) // 验证读取生成文件的权限与内容 const file ctr.file(/srv/app/config/app.conf) const contents await file.contents() console.log(contents) })要点提醒若省略permissions文件权限为默认0644若省略owner文件属主继承镜像/基础容器的默认用户expand: true时若path引用的是容器内的 secret 或 volatile 环境变量调用会直接失败属预期保护行为需要属主跟随容器当前用户时优先使用inheritOwner对应opts.inheritOwner不要与owner同时传入。小结ContainerWithNewFileOpts虽只包含三个可选属性却承载了容器文件写入的三个核心维度路径解析expand环境变量展开、元数据owner属主与安全permissions权限位。理解其默认值0644权限、关闭展开与底层实现expandEnvVar的密钥保护、inheritedOwner的互斥校验、ContainerWithFileLazy的延迟求值能帮助你在编写 Dagger pipeline 时更精准地控制生成文件的行为避免路径展开失效、属主错乱或权限过宽等常见问题。相关代码可进一步查阅 core/schema/container.go、core/container.go 与 sdk/typescript/src/api/client.gen.ts。【免费下载链接】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 中 ContainerWithNewFileOpts 详解用 withNewFile 向容器写入文件【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerContainerWithNewFileOpts是 Dagger TypeScript SDKdagger.io/dagger中Container.withNewFile方法的可选参数类型。本文围绕该类型别名展开逐一剖析其expand、owner、permissions三个可选属性的语义与默认行为并结合 Dagger 仓库中core/schema/container.go与sdk/typescript/src/api/client.gen.ts的源码实现讲清环境变量展开、属主继承、权限落盘等底层机制最后给出可直接运行的实战示例。类型定义速览在 Dagger 的 TypeScript 客户端生成代码中ContainerWithNewFileOpts被定义为普通对象类型object所有属性均为可选项type ContainerWithNewFileOpts { /** * Replace ${VAR} or $VAR in the value of path according to the current * environment variables defined in the container (e.g. /$VAR/foo.txt). */ expand?: boolean /** * A user:group to set for the file. * The user and group can either be an ID (1000:1000) or a name (foo:bar). * If the group is omitted, it defaults to the same as the user. */ owner?: string /** * Permissions of the new file. Example: 0600 */ permissions?: number }该类型定义位于 docs/versioned_docs/version-0.20/reference/typescript/api/client.gen/type-aliases/ContainerWithNewFileOpts.md其内容由 SDK 代码生成器根据 GraphQL schema 自动产出。withNewFile方法本身在 sdk/typescript/src/api/client.gen.ts 中声明用于返回一个新的容器快照在其文件系统中以文本内容新增一个文件。与 withNewFile 的关系ContainerWithNewFileOpts是withNewFile的第三个参数withNewFile( path: string, contents: string, opts?: ContainerWithNewFileOpts, ): Container对应 GraphQL 层的参数结构在 core/schema/container.go 中定义这也是理解各选项默认值的最直接依据type containerWithNewFileArgs struct { Path string Contents string Permissions int default:0644 Owner string default: InheritOwner bool default:false Expand bool default:false }两个值得注意的事实Permissions的默认值是0644即所有者可读写、组和其他人只读即使不传permissions新建文件也拥有合理的安全权限Expand默认关闭路径中的$VAR不会被自动替换需要显式传入expand: true。此外服务端参数中还包含InheritOwner默认为false它对应 SDK 中withNewFile的 JSDoc 所描述的opts.inheritOwner——将文件属主设置为容器当前的用户。这与下文owner参数在语义上互补。属性逐一解析expand?: boolean —— 对路径做环境变量展开expand决定是否按照容器内当前定义的环境变量替换path参数中的${VAR}或$VAR。文档给出的示例是/$VAR/foo.txt当容器内存在名为VAR的环境变量时该路径会被展开为对应值。其底层实现在 core/schema/container.go 的expandEnvVar函数中关键逻辑为expanded : os.Expand(input, func(k string) string { // set error if its a secret env variable if slices.Contains(secretEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with secret env variable %q, k) return } if slices.Contains(volatileEnvs, k) { secretEnvFoundError fmt.Errorf(expand cannot be used with volatile env variable %q, k) return } v, _ : core.LookupEnv(cfg.Env, k) return v })三点关键细节只针对路径展开作用域仅限于path参数不影响contents文件内容基于容器自身环境替换源是容器镜像配置cfg.Env中的环境变量而非宿主机或客户端进程的环境变量安全约束如果路径中引用的变量名是密钥环境变量secret或易变环境变量volatile envexpandEnvVar会直接返回错误拒绝展开。这是为了防止通过路径回显泄露敏感值。从源码结构看os.Expand同时支持$VAR与${VAR}两种语法与文档描述一致。owner?: string —— 设置文件属主owner指定新建文件的所有者格式为user:group。按文档说明用户与组可以是ID如1000:1000或名称如foo:bar组省略时只传1000或foo组默认与用户相同。服务端对属主的解析入口在 core/schema/container.go 的inheritedOwner函数注意它与inheritOwner的关系func inheritedOwner(parent dagql.ObjectResult[*core.Container], owner string, inheritOwner bool) (string, error) { if !inheritOwner { return owner, nil } if owner ! { return , errors.New(cannot set both owner and inheritOwner) } return parent.Self().Config.User, nil }由此可以得出两条行为准则owner与inheritOwner互斥同时设置会报错cannot set both owner and inheritOwner当inheritOwner: true时属主直接取父容器的Config.User即容器当前用户。permissions?: number —— 文件权限位permissions以数字形式给出新建文件的权限位文档示例为0600。结合服务端默认值可知未传时使用默认值0644传0表示不设置服务端仅在args.Permissions ! 0时才把权限附加到内部创建的file节点上见withNewFile实现。该值最终作用于通过内部file节点创建的文件对象并随文件一同写入容器文件系统。源码级实现流程withNewFile在 core/schema/container.go 中的执行链路大致如下路径预处理调用expandEnvVar依据Expand标志决定是否展开路径中的变量拆分文件名用filepath.Split(filepath.Clean(path))提取文件名并将其作为file节点的name与contents若权限非 0 则附带permissions克隆父容器调用cloneContainerForSchemaChild基于父容器复制文件系统、挂载点、元数据、镜像配置、环境变量等保证操作不可变immutable返回的是新容器快照解析属主通过inheritedOwner确定最终owner挂载懒状态构造core.ContainerWithFileLazy见 core/container.go把父容器 路径 文件源 属主记录为待求值lazy状态真正写入文件系统推迟到该容器被实际求值如执行export、file读取或运行容器时进行。这一设计保证了 Dagger 的延迟执行语义withNewFile本身只描述变更不触发任何 IO所有文件系统操作都发生在求值阶段。实战示例下面是一个完整的 TypeScript 示例综合使用三个选项import { connect } from dagger.io/dagger connect(async (client) { const ctr client .container() .from(alpine:latest) .withEnvVariable(APP_HOME, /srv/app) .withNewFile(/$APP_HOME/config/app.conf, log_level debug, { expand: true, // /$APP_HOME/config/app.conf - /srv/app/config/app.conf owner: 1000:1000, // 属主 user:group组省略时默认同 user permissions: 0o600, // 仅属主可读写 }) // 验证读取生成文件的权限与内容 const file ctr.file(/srv/app/config/app.conf) const contents await file.contents() console.log(contents) })要点提醒若省略permissions文件权限为默认0644若省略owner文件属主继承镜像/基础容器的默认用户expand: true时若path引用的是容器内的 secret 或 volatile 环境变量调用会直接失败属预期保护行为需要属主跟随容器当前用户时优先使用inheritOwner对应opts.inheritOwner不要与owner同时传入。小结ContainerWithNewFileOpts虽只包含三个可选属性却承载了容器文件写入的三个核心维度路径解析expand环境变量展开、元数据owner属主与安全permissions权限位。理解其默认值0644权限、关闭展开与底层实现expandEnvVar的密钥保护、inheritedOwner的互斥校验、ContainerWithFileLazy的延迟求值能帮助你在编写 Dagger pipeline 时更精准地控制生成文件的行为避免路径展开失效、属主错乱或权限过宽等常见问题。相关代码可进一步查阅 core/schema/container.go、core/container.go 与 sdk/typescript/src/api/client.gen.ts。【免费下载链接】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），仅供参考
