 抓取遠(yuǎn)程文件并可控落盤)
解析 Dagger TypeScript SDK 的 ClientHttpOpts 類型用 client.http() 抓取遠(yuǎn)程文件并可控落盤【免費(fèi)下載鏈接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/dagger本文圍繞 Dagger v0.20 TypeScript SDK 參考文檔中的ClientHttpOpts類型別名展開完整繼承該參考頁對(duì)authHeader、experimentalServiceHost、name、permissions四個(gè)可選屬性的定義并結(jié)合倉庫中引擎?zhèn)鹊?Go 源碼core/schema/http.go、core/http.go剖析每個(gè)選項(xiàng)在 DAG 執(zhí)行中的真實(shí)作用、默認(rèn)值與版本邊界讀完即可理解client.http()如何把任意 URL 內(nèi)容安全地轉(zhuǎn)換為一個(gè)可掛載、可緩存的File對(duì)象。一、ClientHttpOpts 是什么ClientHttpOpts是 Dagger TypeScript SDK 中Client類方法http()的可選參數(shù)類型。官方 v0.20 參考文檔將其定義為/** * ClientHttpOpts object */即一個(gè)純對(duì)象類型別名其中所有屬性均為optional可選。該類型由 SDK 的 codegen 流程從引擎的 GraphQL Schema 自動(dòng)生成參考頁位于 ClientHttpOpts 類型別名文檔可在 api/client.gen 模塊總覽 的 Type Aliases 列表中找到它。對(duì)應(yīng)地Client.http()的簽名為見 Client 類參考文檔http(url: string, opts?: ClientHttpOpts): File其語義是返回一個(gè)包含 HTTP 遠(yuǎn)程 URL 內(nèi)容的File對(duì)象Returns a file containing an http remote url content。也就是說ClientHttpOpts控制的是下載回來的內(nèi)容以什么文件名保存、什么權(quán)限落盤、用哪個(gè) Secret 做鑒權(quán)、以及是否需要先啟動(dòng)一個(gè) Service 才能訪問該 URL這四件事。二、四個(gè)可選屬性逐一解讀v0.20 參考頁完整定義了以下四個(gè)屬性下面逐一繼承原文檔描述并結(jié)合源碼展開。屬性類型必填說明原文檔描述authHeaderSecret否用于填充 Authorization HTTP 請(qǐng)求頭的 SecretexperimentalServiceHostService否在抓取 URL 之前必須先啟動(dòng)的一個(gè) Servicenamestring否文件使用的文件名默認(rèn)為 URL 的最后一段permissionsnumber否設(shè)置到文件上的權(quán)限1.name文件名推導(dǎo)規(guī)則原文檔說明File name to use for the file. Defaults to the last part of the URL.用于文件的文件名默認(rèn)為 URL 的最后一段。引擎?zhèn)鹊耐茖?dǎo)邏輯在 httpPath 中實(shí)現(xiàn)可以確認(rèn)具體行為若顯式傳了name直接使用該值否則用url.Parse解析 URL取filepath.Base(parsed.Path)作為文件名若解析結(jié)果為空、.或/例如 URL 以路徑結(jié)尾則兜底使用index。這意味著對(duì)https://example.com/spec.json不傳name時(shí)得到文件名為spec.json而對(duì)https://example.com/這樣的裸 URL默認(rèn)文件名會(huì)是index。需要穩(wěn)定文件名例如后續(xù)用于.withNewFile掛載時(shí)建議顯式指定name。2.permissions默認(rèn)值 0600原文檔僅說明Permissions to set on the file設(shè)置到文件上的權(quán)限。倉庫源碼給出了關(guān)鍵默認(rèn)值在 httpSchema.http 中permissions : int(args.Permissions.GetOr(dagql.Int(0600)))即不傳permissions時(shí)下載得到的File權(quán)限默認(rèn)為0600僅屬主可讀寫。這是一個(gè)偏保守的安全默認(rèn)抓取到的遠(yuǎn)程內(nèi)容默認(rèn)不賦予執(zhí)行位。若要產(chǎn)出可執(zhí)行腳本如下載install.sh后直接運(yùn)行應(yīng)顯式傳入如0o755之類的權(quán)限值。3.authHeader以 Secret 形式注入 Authorization 頭原文檔說明Secret used to populate the Authorization HTTP header用于填充 Authorization HTTP 請(qǐng)求頭的 Secret。注意其類型是 SDK 的Secret對(duì)象而非明文string這是 Dagger 的通用敏感信息處理約定憑證以不透明對(duì)象在 DAG 中傳遞落明文時(shí)才解密。從 resolveHTTPSessionContext 的源碼可以看到引擎的處理方式先加載Secret再調(diào)用Plaintext(ctx)取出明文作為Authorization請(qǐng)求頭的值。這使client.http()天然適配私有倉庫、帶 token 的制品下載等場(chǎng)景且憑證不會(huì)以字符串形式出現(xiàn)在 DAG 參數(shù)快照中。4.experimentalServiceHost先起服務(wù)再抓 URL原文檔說明A service which must be started before the URL is fetched.在 URL 抓取前必須先啟動(dòng)的一個(gè) Service。這個(gè)選項(xiàng)解決的是目標(biāo) URL 只存在于 Dagger 引擎內(nèi)部網(wǎng)絡(luò)的問題例如訪問一個(gè)由 DAG 啟動(dòng)的本地 HTTP 服務(wù)。源碼 resolveHTTPSessionContext 展示了完整機(jī)制加載傳入的Service對(duì)象計(jì)算其ContentPreferredDigest通過svc.Hostname(ctx, svcDig)解析出該服務(wù)的內(nèi)部主機(jī)名構(gòu)造core.ServiceBinding{Service: svc, Hostname: host}調(diào)用svcs.StartBindings(...)啟動(dòng)綁定并返回一個(gè)detach函數(shù)用于請(qǐng)求結(jié)束后的資源清理。從源碼結(jié)構(gòu)看該綁定僅在單次請(qǐng)求生命周期內(nèi)保持啟動(dòng)defer detach()不會(huì)污染會(huì)話中其他無關(guān)的網(wǎng)絡(luò)命名空間。屬性名帶experimental前綴表示該能力在 v0.20 時(shí)代仍處于實(shí)驗(yàn)狀態(tài)API 形態(tài)可能調(diào)整生產(chǎn)使用前應(yīng)確認(rèn)所用版本的穩(wěn)定性。三、兩條抓取路徑有憑證走直連無憑證走惰性狀態(tài)結(jié)合 core/schema/http.go 的實(shí)現(xiàn)client.http()在引擎?zhèn)炔⒎强傋咄粭l路徑。在 http 解析函數(shù) 中可以清楚看到分支邏輯當(dāng)authHeader或experimentalServiceHost任一被設(shè)置時(shí)引擎先解析會(huì)話上下文取 Secret 明文、啟動(dòng)服務(wù)綁定然后直接調(diào)用 core.FetchHTTPFile 完成一次同步抓取得到core.HTTPFetchResult定義見 core/http.go#L58兩個(gè)選項(xiàng)都未設(shè)置時(shí)引擎改走_(dá)httpState內(nèi)部對(duì)象路徑——先構(gòu)造一個(gè)僅記錄url的HTTPState再在其上執(zhí)行_resolve帶checksum、permissions、name。從源碼結(jié)構(gòu)看這條路徑是按會(huì)話解析一次resolve once per session的惰性/可持久化狀態(tài)設(shè)計(jì)_httpState被標(biāo)記為IsPersistable()使同一個(gè) URL 的抓取結(jié)果可以在會(huì)話內(nèi)被緩存復(fù)用而不是重復(fù)下載。兩條路徑最終都匯聚到newHTTPFileResult它用文件路徑、權(quán)限、內(nèi)容 digest、Last-Modified 與期望 checksum 做一次哈希得到該File的ContentDigest見 newHTTPFileResult。這解釋了為什么改permissions、name或checksum會(huì)改變最終File的身份——它們都參與結(jié)果 digest 的計(jì)算。四、用法示例綜合上述文檔與源碼事實(shí)ClientHttpOpts的典型用法如下基于 v0.20 API 面import { dag } from dagger.io/dagger // 1) 最簡(jiǎn)用法文件名取 URL 最后一段權(quán)限默認(rèn) 0600 const readme dag.http(https://example.com/readme.txt) // 2) 顯式控制文件名與權(quán)限下載可執(zhí)行安裝腳本 const installer dag.http(https://example.com/install.sh, { name: install.sh, permissions: 0o755, }) // 3) 帶鑒權(quán)用 Secret 填充 Authorization 請(qǐng)求頭 const token dag.setSecret(registry-token) const artifact dag.http(https://private.example.com/pkg.tar.gz, { authHeader: Bearer ${token.plaintext()}, name: pkg.tar.gz, }) // 4) 依賴 DAG 內(nèi)啟動(dòng)的服務(wù)先起 Service再抓取其內(nèi)部 URL const svc container.asService() const page dag.http(http://127.0.0.1:8080/health, { experimentalServiceHost: svc, })示例 3 中為保持簡(jiǎn)潔以plaintext()構(gòu)造 Secret實(shí)際模塊代碼中更推薦直接用dag.setSecret(...)傳入已知 Secret 對(duì)象避免明文流經(jīng)函數(shù)參數(shù)。示例 4 的主機(jī)名解析由引擎依據(jù) Service 內(nèi)容 digest 自動(dòng)完成svc.Hostname調(diào)用方無需手工綁定網(wǎng)絡(luò)。五、版本邊界v0.20 參考頁與當(dāng)前倉庫源碼的差異本文以 v0.20 的 ClientHttpOpts 參考頁 為主體需向讀者說明兩處版本邊界checksum屬性的版本門控。v0.20 參考頁只列出 4 個(gè)屬性而當(dāng)前倉庫中生成的 TypeScript SDK 源文件 sdk/typescript/src/api/client.gen.ts#L2916-L2941 中同一類型多了一個(gè)可選的checksum?: stringExpected digest of the downloaded content (e.g., sha256:...)。對(duì)應(yīng)地引擎 Schema 中該參數(shù)被注冊(cè)為View(AfterVersion(v0.21.0))見 core/schema/http.go#L28-L29即 checksum 能力自 v0.21.0 起才對(duì)外可見。使用 v0.20 SDK 時(shí)不應(yīng)依賴該字段在更新版本中checksum可強(qiáng)制校驗(yàn)下載內(nèi)容 digest與newHTTPFileResult中的 digest 計(jì)算相配合構(gòu)成供應(yīng)鏈完整性校驗(yàn)的抓手。參考文檔隨版本歸檔。docs/versioned_docs/version-0.20/下的 API 參考是 v0.20 快照而倉庫根部的 sdk/typescript 反映的是當(dāng)前開發(fā)的 API 面。若以 v0.20 為基線做集成屬性集合應(yīng)以本文第二節(jié)的 4 屬性表為準(zhǔn)。六、小結(jié)ClientHttpOpts雖然只是一個(gè)四屬性的對(duì)象類型別名但它完整表達(dá)了 Dagger 把網(wǎng)絡(luò)抓取納入不可變 DAG 的設(shè)計(jì)取向name與permissions決定落盤形態(tài)默認(rèn)文件名取 URL 末段、默認(rèn)權(quán)限 0600authHeader以Secret抽象承載憑證experimentalServiceHost則打通了引擎內(nèi)服務(wù) → HTTP 抓取的內(nèi)部網(wǎng)絡(luò)鏈路。理解了 core/schema/http.go 中直連/惰性雙路徑的分支與結(jié)果 digest 的構(gòu)成你就能準(zhǔn)確預(yù)測(cè)每次參數(shù)變化對(duì)緩存與File身份的影響并在 v0.20 及更新版本中穩(wěn)妥地使用client.http()獲取遠(yuǎn)程內(nèi)容?！久赓M(fèi)下載鏈接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/dagger創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 解析 Dagger TypeScript SDK 的 ClientHttpOpts 類型：用 client.http() 抓取遠(yuǎn)程文件并可控落盤
解析 Dagger TypeScript SDK 的 ClientHttpOpts 類型用 client.http() 抓取遠(yuǎn)程文件并可控落盤【免費(fèi)下載鏈接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/dagger本文圍繞 Dagger v0.20 TypeScript SDK 參考文檔中的ClientHttpOpts類型別名展開完整繼承該參考頁對(duì)authHeader、experimentalServiceHost、name、permissions四個(gè)可選屬性的定義并結(jié)合倉庫中引擎?zhèn)鹊?Go 源碼core/schema/http.go、core/http.go剖析每個(gè)選項(xiàng)在 DAG 執(zhí)行中的真實(shí)作用、默認(rèn)值與版本邊界讀完即可理解client.http()如何把任意 URL 內(nèi)容安全地轉(zhuǎn)換為一個(gè)可掛載、可緩存的File對(duì)象。一、ClientHttpOpts 是什么ClientHttpOpts是 Dagger TypeScript SDK 中Client類方法http()的可選參數(shù)類型。官方 v0.20 參考文檔將其定義為/** * ClientHttpOpts object */即一個(gè)純對(duì)象類型別名其中所有屬性均為optional可選。該類型由 SDK 的 codegen 流程從引擎的 GraphQL Schema 自動(dòng)生成參考頁位于 ClientHttpOpts 類型別名文檔可在 api/client.gen 模塊總覽 的 Type Aliases 列表中找到它。對(duì)應(yīng)地Client.http()的簽名為見 Client 類參考文檔http(url: string, opts?: ClientHttpOpts): File其語義是返回一個(gè)包含 HTTP 遠(yuǎn)程 URL 內(nèi)容的File對(duì)象Returns a file containing an http remote url content。也就是說ClientHttpOpts控制的是下載回來的內(nèi)容以什么文件名保存、什么權(quán)限落盤、用哪個(gè) Secret 做鑒權(quán)、以及是否需要先啟動(dòng)一個(gè) Service 才能訪問該 URL這四件事。二、四個(gè)可選屬性逐一解讀v0.20 參考頁完整定義了以下四個(gè)屬性下面逐一繼承原文檔描述并結(jié)合源碼展開。屬性類型必填說明原文檔描述authHeaderSecret否用于填充 Authorization HTTP 請(qǐng)求頭的 SecretexperimentalServiceHostService否在抓取 URL 之前必須先啟動(dòng)的一個(gè) Servicenamestring否文件使用的文件名默認(rèn)為 URL 的最后一段permissionsnumber否設(shè)置到文件上的權(quán)限1.name文件名推導(dǎo)規(guī)則原文檔說明File name to use for the file. Defaults to the last part of the URL.用于文件的文件名默認(rèn)為 URL 的最后一段。引擎?zhèn)鹊耐茖?dǎo)邏輯在 httpPath 中實(shí)現(xiàn)可以確認(rèn)具體行為若顯式傳了name直接使用該值否則用url.Parse解析 URL取filepath.Base(parsed.Path)作為文件名若解析結(jié)果為空、.或/例如 URL 以路徑結(jié)尾則兜底使用index。這意味著對(duì)https://example.com/spec.json不傳name時(shí)得到文件名為spec.json而對(duì)https://example.com/這樣的裸 URL默認(rèn)文件名會(huì)是index。需要穩(wěn)定文件名例如后續(xù)用于.withNewFile掛載時(shí)建議顯式指定name。2.permissions默認(rèn)值 0600原文檔僅說明Permissions to set on the file設(shè)置到文件上的權(quán)限。倉庫源碼給出了關(guān)鍵默認(rèn)值在 httpSchema.http 中permissions : int(args.Permissions.GetOr(dagql.Int(0600)))即不傳permissions時(shí)下載得到的File權(quán)限默認(rèn)為0600僅屬主可讀寫。這是一個(gè)偏保守的安全默認(rèn)抓取到的遠(yuǎn)程內(nèi)容默認(rèn)不賦予執(zhí)行位。若要產(chǎn)出可執(zhí)行腳本如下載install.sh后直接運(yùn)行應(yīng)顯式傳入如0o755之類的權(quán)限值。3.authHeader以 Secret 形式注入 Authorization 頭原文檔說明Secret used to populate the Authorization HTTP header用于填充 Authorization HTTP 請(qǐng)求頭的 Secret。注意其類型是 SDK 的Secret對(duì)象而非明文string這是 Dagger 的通用敏感信息處理約定憑證以不透明對(duì)象在 DAG 中傳遞落明文時(shí)才解密。從 resolveHTTPSessionContext 的源碼可以看到引擎的處理方式先加載Secret再調(diào)用Plaintext(ctx)取出明文作為Authorization請(qǐng)求頭的值。這使client.http()天然適配私有倉庫、帶 token 的制品下載等場(chǎng)景且憑證不會(huì)以字符串形式出現(xiàn)在 DAG 參數(shù)快照中。4.experimentalServiceHost先起服務(wù)再抓 URL原文檔說明A service which must be started before the URL is fetched.在 URL 抓取前必須先啟動(dòng)的一個(gè) Service。這個(gè)選項(xiàng)解決的是目標(biāo) URL 只存在于 Dagger 引擎內(nèi)部網(wǎng)絡(luò)的問題例如訪問一個(gè)由 DAG 啟動(dòng)的本地 HTTP 服務(wù)。源碼 resolveHTTPSessionContext 展示了完整機(jī)制加載傳入的Service對(duì)象計(jì)算其ContentPreferredDigest通過svc.Hostname(ctx, svcDig)解析出該服務(wù)的內(nèi)部主機(jī)名構(gòu)造core.ServiceBinding{Service: svc, Hostname: host}調(diào)用svcs.StartBindings(...)啟動(dòng)綁定并返回一個(gè)detach函數(shù)用于請(qǐng)求結(jié)束后的資源清理。從源碼結(jié)構(gòu)看該綁定僅在單次請(qǐng)求生命周期內(nèi)保持啟動(dòng)defer detach()不會(huì)污染會(huì)話中其他無關(guān)的網(wǎng)絡(luò)命名空間。屬性名帶experimental前綴表示該能力在 v0.20 時(shí)代仍處于實(shí)驗(yàn)狀態(tài)API 形態(tài)可能調(diào)整生產(chǎn)使用前應(yīng)確認(rèn)所用版本的穩(wěn)定性。三、兩條抓取路徑有憑證走直連無憑證走惰性狀態(tài)結(jié)合 core/schema/http.go 的實(shí)現(xiàn)client.http()在引擎?zhèn)炔⒎强傋咄粭l路徑。在 http 解析函數(shù) 中可以清楚看到分支邏輯當(dāng)authHeader或experimentalServiceHost任一被設(shè)置時(shí)引擎先解析會(huì)話上下文取 Secret 明文、啟動(dòng)服務(wù)綁定然后直接調(diào)用 core.FetchHTTPFile 完成一次同步抓取得到core.HTTPFetchResult定義見 core/http.go#L58兩個(gè)選項(xiàng)都未設(shè)置時(shí)引擎改走_(dá)httpState內(nèi)部對(duì)象路徑——先構(gòu)造一個(gè)僅記錄url的HTTPState再在其上執(zhí)行_resolve帶checksum、permissions、name。從源碼結(jié)構(gòu)看這條路徑是按會(huì)話解析一次resolve once per session的惰性/可持久化狀態(tài)設(shè)計(jì)_httpState被標(biāo)記為IsPersistable()使同一個(gè) URL 的抓取結(jié)果可以在會(huì)話內(nèi)被緩存復(fù)用而不是重復(fù)下載。兩條路徑最終都匯聚到newHTTPFileResult它用文件路徑、權(quán)限、內(nèi)容 digest、Last-Modified 與期望 checksum 做一次哈希得到該File的ContentDigest見 newHTTPFileResult。這解釋了為什么改permissions、name或checksum會(huì)改變最終File的身份——它們都參與結(jié)果 digest 的計(jì)算。四、用法示例綜合上述文檔與源碼事實(shí)ClientHttpOpts的典型用法如下基于 v0.20 API 面import { dag } from dagger.io/dagger // 1) 最簡(jiǎn)用法文件名取 URL 最后一段權(quán)限默認(rèn) 0600 const readme dag.http(https://example.com/readme.txt) // 2) 顯式控制文件名與權(quán)限下載可執(zhí)行安裝腳本 const installer dag.http(https://example.com/install.sh, { name: install.sh, permissions: 0o755, }) // 3) 帶鑒權(quán)用 Secret 填充 Authorization 請(qǐng)求頭 const token dag.setSecret(registry-token) const artifact dag.http(https://private.example.com/pkg.tar.gz, { authHeader: Bearer ${token.plaintext()}, name: pkg.tar.gz, }) // 4) 依賴 DAG 內(nèi)啟動(dòng)的服務(wù)先起 Service再抓取其內(nèi)部 URL const svc container.asService() const page dag.http(http://127.0.0.1:8080/health, { experimentalServiceHost: svc, })示例 3 中為保持簡(jiǎn)潔以plaintext()構(gòu)造 Secret實(shí)際模塊代碼中更推薦直接用dag.setSecret(...)傳入已知 Secret 對(duì)象避免明文流經(jīng)函數(shù)參數(shù)。示例 4 的主機(jī)名解析由引擎依據(jù) Service 內(nèi)容 digest 自動(dòng)完成svc.Hostname調(diào)用方無需手工綁定網(wǎng)絡(luò)。五、版本邊界v0.20 參考頁與當(dāng)前倉庫源碼的差異本文以 v0.20 的 ClientHttpOpts 參考頁 為主體需向讀者說明兩處版本邊界checksum屬性的版本門控。v0.20 參考頁只列出 4 個(gè)屬性而當(dāng)前倉庫中生成的 TypeScript SDK 源文件 sdk/typescript/src/api/client.gen.ts#L2916-L2941 中同一類型多了一個(gè)可選的checksum?: stringExpected digest of the downloaded content (e.g., sha256:...)。對(duì)應(yīng)地引擎 Schema 中該參數(shù)被注冊(cè)為View(AfterVersion(v0.21.0))見 core/schema/http.go#L28-L29即 checksum 能力自 v0.21.0 起才對(duì)外可見。使用 v0.20 SDK 時(shí)不應(yīng)依賴該字段在更新版本中checksum可強(qiáng)制校驗(yàn)下載內(nèi)容 digest與newHTTPFileResult中的 digest 計(jì)算相配合構(gòu)成供應(yīng)鏈完整性校驗(yàn)的抓手。參考文檔隨版本歸檔。docs/versioned_docs/version-0.20/下的 API 參考是 v0.20 快照而倉庫根部的 sdk/typescript 反映的是當(dāng)前開發(fā)的 API 面。若以 v0.20 為基線做集成屬性集合應(yīng)以本文第二節(jié)的 4 屬性表為準(zhǔn)。六、小結(jié)ClientHttpOpts雖然只是一個(gè)四屬性的對(duì)象類型別名但它完整表達(dá)了 Dagger 把網(wǎng)絡(luò)抓取納入不可變 DAG 的設(shè)計(jì)取向name與permissions決定落盤形態(tài)默認(rèn)文件名取 URL 末段、默認(rèn)權(quán)限 0600authHeader以Secret抽象承載憑證experimentalServiceHost則打通了引擎內(nèi)服務(wù) → HTTP 抓取的內(nèi)部網(wǎng)絡(luò)鏈路。理解了 core/schema/http.go 中直連/惰性雙路徑的分支與結(jié)果 digest 的構(gòu)成你就能準(zhǔn)確預(yù)測(cè)每次參數(shù)變化對(duì)緩存與File身份的影響并在 v0.20 及更新版本中穩(wěn)妥地使用client.http()獲取遠(yuǎn)程內(nèi)容?！久赓M(fèi)下載鏈接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud項(xiàng)目地址: https://gitcode.com/GitHub_Trending/da/dagger創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考