Metadata-Version: 2.4
Name: fufu-cloud-cli
Version: 0.8.0
Summary: FUFU Cloud CLI for tenant-scoped mock cloud development and deployment
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML==6.0.3
Requires-Dist: tomli==2.2.1; python_version < "3.11"
Provides-Extra: yaml
Requires-Dist: PyYAML==6.0.3; extra == "yaml"
Provides-Extra: test
Requires-Dist: boto3==1.40.66; extra == "test"
Provides-Extra: terraform
Requires-Dist: python-hcl2==7.3.1; extra == "terraform"
Dynamic: license-file

# FUFU Cloud CLI

以五個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
`gcloud-fufu`、`az-fufu`、`wrangler-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。

0.8.0 包含資源配額、分段傳輸、Terraform 核心子集與 Cloudflare 靜態部署／R2。需要同步更新服務端；CLI 安裝成功不表示任意 FUFU 服務端都已有這些能力。

## Cloudflare 前端部署與 R2

```bash
pip install 'fufu-cloud-cli==0.8.0'
export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json
wrangler-fufu capabilities
wrangler-fufu pages project create frontend --production-branch main
npm run build
wrangler-fufu pages deploy dist --project-name frontend --branch main
wrangler-fufu pages deployment list --project-name frontend
wrangler-fufu deploy --assets dist --name frontend-assets
wrangler-fufu r2 bucket create frontend-files
wrangler-fufu r2 object put frontend-files/example.txt --file example.txt --remote
```

支援 Wrangler JSON、JSONC、TOML，以及 `--config`、`--cwd`、`--env`。Pages 使用
`pages_build_output_dir`；Workers Static Assets 使用 `assets.directory`，SPA 可明確設定
`assets.not_found_handling = "single-page-application"`。正式與預覽網址分開，正式部署完整
上傳且校驗通過才切换入口；Pages 可用 `pages deployment rollback ID --project-name NAME` 回滾。

這些命令提供真正的靜態 HTTP hosting，**不執行 Workers JavaScript 或 Pages Functions**。
KV、D1、Durable Objects、Queues、Cron、自訂網域、SSR 與全球 CDN 快取未實作；
相關配置會被拒絕。API credential、S3 endpoint 與帳號識別使用 FUFU 值。
目前不讀取官方 `CLOUDFLARE_API_TOKEN`；使用 FUFU credential JSON，避免誤用正式金鑰。

R2 支援 bucket／object、分段上傳、範圍下載、CORS、預設私人及可開關公開開發網址。
原生 boto3／AWS S3 SDK 可使用 credential JSON 中的 `r2_endpoint`、`r2_access_key_id`、
`r2_secret_access_key`，region 為 `auto` 且使用 path-style addressing。
SDK checksum 配置使用 `WHEN_REQUIRED`；SigV4、預簽 PUT／GET、Content-MD5、
基本自訂 metadata 與 multipart 已支援。未支援條件寫入、CopyObject、版本／生命週期、
自訂加密，以及 Cache-Control／Content-Encoding 等寫入 metadata；會明確回錯，不靜默忽略。
沒有 Cloudflare Terraform provider 相容層。

静態檔案上限 25 MiB／每次最多 100,000 檔；R2 物件上限 5 TiB、S3 單次或分段上限
5 GiB、最多 10,000 段。可用磁碟、請求逾時與併發容量仍會限制實際可接受大小。
公開部署前拒絕私人路徑、符號連結與已知 credential 格式；此檢查不是所有機密的偵測器。
FUFU 沒有 CDN 快取，入口回覆 `Cache-Control: no-store`，不模擬一次成功的 cache purge。

## 安裝

需要 Python 3.10 以上。Python 套件預設包含 YAML 相依套件：

```bash
pip install fufu-cloud-cli
fufu --version
```

npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
呼叫相同的 Python CLI。0.8.0 的 npm 建置包內附純 Python YAML／TOML parser，沒有安裝腳本，
不會自行下載 Python 或執行 pip。

```bash
npm install fufu-cloud-cli
npx --no-install fufu --version
npx --no-install aws-fufu --help
```

全域安裝可使用 `npm install -g fufu-cloud-cli`。預設 Python 指令為 `python3`；
若名稱不同，將 `FUFU_PYTHON` 設成可信 Python 執行檔的路徑。
本機 Docker backend 只支援 Linux 與本機 Unix socket。API backend
不需要安裝 Docker；其他作業系統仍須另外驗證其 Python 與網路環境。

## 憑證與 CI

此工作樹也提供 `fufu terraform`：以官方 AWS／Google Terraform provider
管理 Lambda ZIP、Cloud Run v2、IAM 與服務入口的明列子集，並使用獨立的
FUFU state。Terraform 需另行安裝，Python 使用 `fufu-cloud-cli[terraform]`
extra；npm 使用的 Python 也需要該 extra 的相依套件。使用 0.8.0 以上版本。
GCS／S3、Functions Gen 1／Gen 2 等一般 CLI 能力
不表示官方 Terraform 資源已相容。正式環境使用正常 Terraform、正式認證
與獨立 state，不可直接搬用 FUFU state。

向 FUFU Cloud 管理者取得該租戶、該 provider 的專用 credential JSON。
CLI 不附預設帳號、共用金鑰或可用的租戶憑證，也不讀取 `.env`、瀏覽器
Cookie 或正式雲端登入工作階段。

在 CI 的秘密管理功能中注入 credential 檔案，並設定：

```bash
export FUFU_BACKEND=api
export FUFU_AWS_CREDENTIAL_FILE=/run/secrets/fufu-aws.json
export FUFU_GCP_CREDENTIAL_FILE=/run/secrets/fufu-gcp.json
export FUFU_AZURE_CREDENTIAL_FILE=/run/secrets/fufu-azure.json
export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json

fufu auth whoami --provider aws
aws-fufu sts get-caller-identity
gcloud-fufu auth list
az-fufu account show
wrangler-fufu whoami
```

credential 內含 FUFU endpoint。`FUFU_ENDPOINT` 可明確覆寫目的地：僅限
你信任且獲授權接收 credential 的 FUFU 服務。正式網路需使用 HTTPS；
只有 loopback 允許 HTTP。TLS 憑證驗證保持開啟，不跟隨重新導向，
不繼承系統 HTTP proxy。

一般命令交換短期權杖並在結束時嘗試撤銷。`fufu auth assume-role`
可建立受限 session 檔，檔案以排他方式建立且權限為 `0600`；請勿提交。
FUFU credential 與 session 檔仍屬秘密，必須由作業系統和 CI 控制存取。
原生雲端的 GitHub auth actions、OIDC 和 OAuth 不直接相容。
Lambda Function URL 的 AWS_IAM 支援長效 FUFU access key 的 SigV4 header signing；管理 API 仍使用 FUFU token。

## 部署與支援範圍

```bash
fufu capabilities
fufu capabilities --remote --provider gcp --require cloud-run-http
gcloud-fufu run deploy example --image approved-image:tag
gcloud-fufu run deploy example --source ./prepared-asgi.zip --entry-point main:app
gcloud-fufu functions deploy example-function --gen2 \
  --runtime python312 --source ./function --entry-point handler --trigger-http
aws-fufu lambda list-functions
```

自訂映像需先由 FUFU 管理者準備及核准。API 模式的 Cloud Run `--source`
接受已封裝 Uvicorn 與相依套件的 Python 3.12 ASGI ZIP／乾淨目錄，自動離線建置、
檢查映像並核准到目前租戶；不需要主機 SSH 或每次人工核准。
`--entry-point module:app` 是 FUFU 擴充旗標，預設 `main:app`。
目前來源版本的 FUFU 配方上限為 ZIP 512 MiB、解壓縮 2 GiB、100000 個檔案；不接受隱藏檔、Dockerfile、
自訂安裝設定或非空 requirements.txt。相依套件需在 CI 封裝，服務端不執行安裝 hook。
這是固定 ASGI 配方，不提供完整 Cloud Build 或 registry API。
成功回應包含 `build.status`、`imageDigest` 與來源包雜湊；自動核准映像
僅供該租戶目前服務使用，取代或刪除最後一個引用後不再開放重用。

Function 來源會上傳指定目錄中的
Python 與 requirements 檔；Lambda 會上傳指定的 ZIP。請使用只含必要程式碼的
目錄或 ZIP，先移除硬編碼秘密、個人資料與不需要的檔案。
CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。

| 服務 | 可用範圍與主要限制 |
| --- | --- |
| Cloud Run | 已核准 HTTP 容器或 API 自動建置 Python ASGI 來源；支援配置後的 HTTPS 入口、Invoker policy；無 autoscaling、traffic splitting、Jobs |
| Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
| AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新、BUFFERED Function URL；ZIP 50 MiB／解壓 250 MiB，同步 payload 6 MiB |
| GCS / S3 | bucket 與 object 子集；分段上傳／串流下載，受主機磁碟限制；已驗證超過 1 GiB，無 versioning / signed URL |
| DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
| AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
| API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |
| Azure | account 與資源群組目錄；尚無 Azure Functions 或其他 Azure runtime |
| EC2 / ECS / App Engine 等 | 部分只有 mock 目錄；不能視為執行中的 VM、Task 或應用 |

`fufu capabilities` 是隨版支援清單；`--remote` 另外查詢服務端能力。
`implemented` 代表明列子集已接入，`partial`、`mock-only`、`unsupported`
均不代表完整服務可用。未支援命令、旗標、YAML 欄位會拒絕，CI 應檢查退出碼。

## YAML / JSON

Cloud Run manifest 支援 `serving.knative.dev/v1`、`kind: Service`、
`metadata.name`、單一 container 的 image / port / env，以及明列的 service account。
服務 metadata.annotations 支援 `run.googleapis.com/ingress`（all／internal）與
`run.googleapis.com/invoker-iam-disabled`（字串 true／false）。
`fufu plan --file service.yaml` 可在不部署的情況下檢查設定；plan 僅列出環境變數名稱。
相同設定可用 JSON。其他正式雲端欄位需要顯式調整，不能宣稱所有設定無痛相容。

## 隱私與執行邊界

0.7.0 新增服務公開存取。需由平台配置 DNS、HTTPS 入口與 WAF 放行，
`publicAccess.status=ready` 表示入口已配置；仍應由 CI 實際 HTTP 呼叫確認外部可達。

```bash
gcloud-fufu run services update example --allow-unauthenticated --ingress all
gcloud-fufu run services get-iam-policy example
gcloud-fufu run services update example --no-allow-unauthenticated
gcloud-fufu auth print-identity-token --audiences https://app-SERVICE_ID.example.com
aws-fufu lambda create-function-url-config --function-name example --auth-type AWS_IAM
aws-fufu lambda get-function-url-config --function-name example
```

UI 與 CLI 共用同一份服務政策。Cloud Run 與 HTTP Functions 的匿名政策使用
`allUsers` 與對應 Invoker 角色。Lambda `NONE` 必須另加 `lambda:InvokeFunctionUrl`
（`--function-url-auth-type NONE`）和 `lambda:InvokeFunction`
（`--invoked-via-function-url`）兩項資源權限；只設定 NONE 不會自動開放呼叫。
入口支援有界限的普通 HTTP：Lambda 請求與回應各 6 MiB、Gen 1 各 10 MiB、Run／Gen 2 各 32 MiB。
依服務設定等待，期限上限分別為 900／540／3600 秒；外部 CDN 期限另計。每服務每分鐘 6000 次，另有主機容量背壓。
不支援 SSE、WebSocket、串流、STS 暫時金鑰、presigned URL 或真實 VPC。
GCP ID token 由 FUFU 的 RS256 issuer 簽發，綁定精確 audience，15 分鐘後過期；不接受 Google ID token。
`print-identity-token` 明確輸出秘密，應直接放入受控變數，避免 CI 日誌或 shell tracing。

- 套件沒有遙測、廣告、背景更新或安裝時網路腳本。
- API 請求只使用明確提供的 FUFU endpoint 和 credential；不掃描使用者家目錄。
- `whoami` 會輸出目前租戶、provider 與 scope；查詢／invoke 會輸出所要求的資料。
  請將 CI 日誌視為可能包含應用資料，不把敏感查詢結果公開。
- 本機部署會操作 Docker。明確執行 runtime prepare 或 function build 時，
  可能下載固定映像或安裝應用 requirements；不可信 requirements 仍可執行建置程式。
- FUFU 服務端的租戶隔離、IAM、日誌保存與資料保護由服務端負責。
  CLI 的本機檢查不等於對任何遠端部署作永久安全保證。

本套件目前保留著作權，未授予開源授權。套件公開可下載與原始碼採用開源授權
是不同事項；第三方 YAML parser 依其 MIT 授權散布。
