設計: #334

docs/glossary.md

@@ -84,6 +84,11 @@ up の後に VS Code で dev コンテナを開く（docs/specifications/editor-
 | AWS の丸ごとの取り込み | — | ~/.aws/config と ~/.aws/credentials を切り出さずにそのまま 1 つの tar にして AWS_CONFIG_BASE64 へ書くこと。#314 より前の振る舞い | — | — | `docs/specifications/secret-backend.md` |
 | AWS のプロファイルの連なり | — | 選んだ AWS のプロファイルが動くのに要る節。sso_session が指す [sso-session <名前>] と、source_profile が指すプロファイル（たどれる限り） | — | — | `docs/specifications/secret-backend.md` |
 | グループ名の例 | — | エラー文・使い方の文言がグループ名の書き方として示す名前。lib/devbase/env/groups.py の定義 1 か所から出す | — | — | `docs/specifications/secret-backend.md` |
+| プロファイル名の正規化 | — | GCP の鍵ファイル名の拡張子を除いた部分のうち [A-Za-z0-9_] 以外を _ へ置き換え、GCP のプロファイル名（GCP_CREDENTIALS_BASE64_<名前> の <名前>）にすること | — | — | — |
+| ホストの region | — | ホストの ~/.aws/config の、選んだ AWS のプロファイルの節にある region の値。方法 3（Access Key）は [default]、方法 2（SSO Profile）は利用者が入れたプロファイル | — | — | — |
+| region の出所 | — | 参照の AWS_DEFAULT_REGION へ書く値をどこから得たか。参照に既にある・ホストの region・利用者の入力・既定の値（ap-northeast-1）の 4 つ | — | — | — |
+| 鍵の確認の結果 | — | AWS の方法 3 で、ホストの [default] の鍵を取り込むかを決めた結果。受け入れた・断った・確認しなかった（ホストに鍵が無い）の 3 つ。方針が import なら受け入れた。skip ならホストに鍵があれば断った、無ければ確認しなかったになる | — | — | — |
+| 鍵ファイルの発見 | — | ~/gcp-credentials/ の *.json を読み、正規化したプロファイル名から鍵ファイルへの対応を作ること。出力を持たない | — | — | — |
 
 ## スナップショット（`snapshot`）
 

docs/glossary/glossary.json

@@ -656,6 +656,41 @@
       "meaning": "固有の語の検査が当たりにしない行。パスと行の形の組で定め、語を含まない",
       "source": "docs/specifications/ci-checks.md"
     },
+    {
+      "term": "プロファイル名の正規化",
+      "context": "secret",
+      "meaning": "GCP の鍵ファイル名の拡張子を除いた部分のうち [A-Za-z0-9_] 以外を _ へ置き換え、GCP のプロファイル名（GCP_CREDENTIALS_BASE64_<名前> の <名前>）にすること",
+      "source": "",
+      "pending_source": "issues/issue-334-design.md"
+    },
+    {
+      "term": "ホストの region",
+      "context": "secret",
+      "meaning": "ホストの ~/.aws/config の、選んだ AWS のプロファイルの節にある region の値。方法 3（Access Key）は [default]、方法 2（SSO Profile）は利用者が入れたプロファイル",
+      "source": "",
+      "pending_source": "issues/issue-334-design.md"
+    },
+    {
+      "term": "region の出所",
+      "context": "secret",
+      "meaning": "参照の AWS_DEFAULT_REGION へ書く値をどこから得たか。参照に既にある・ホストの region・利用者の入力・既定の値（ap-northeast-1）の 4 つ",
+      "source": "",
+      "pending_source": "issues/issue-334-design.md"
+    },
+    {
+      "term": "鍵の確認の結果",
+      "context": "secret",
+      "meaning": "AWS の方法 3 で、ホストの [default] の鍵を取り込むかを決めた結果。受け入れた・断った・確認しなかった（ホストに鍵が無い）の 3 つ。方針が import なら受け入れた。skip ならホストに鍵があれば断った、無ければ確認しなかったになる",
+      "source": "",
+      "pending_source": "issues/issue-334-design.md"
+    },
+    {
+      "term": "鍵ファイルの発見",
+      "context": "secret",
+      "meaning": "~/gcp-credentials/ の *.json を読み、正規化したプロファイル名から鍵ファイルへの対応を作ること。出力を持たない",
+      "source": "",
+      "pending_source": "issues/issue-334-design.md"
+    },
     {
       "term": "起動の後の処理",
       "context": "post-start",

issues/issue-334-design-decisions.md

@@ -0,0 +1,94 @@
+# #334: 決定の記録
+
+[issue-334-design.md](issue-334-design.md)（#334 の設計）の決定を持つ。不変条件（I1〜I10）と受け入れ条件の番号は、
+設計と要求（[issue-334-requirements.md](issue-334-requirements.md)）のものを指す。
+
+## 決定の記録
+
+### 決定 1: 方法 2 の region も取り込みの方針に従わせる
+
+方法 2 で利用者が入れるのはプロファイル名であり、そのプロファイルの region をホストから参照へ書くことまで
+同意したとは読めない（要求の前提 2）。方法 3 だけを直すと、同じ「ホストの `~/.aws/config` から読んで参照へ書く」
+値が、方法によって方針に従ったり従わなかったりする。方法 2 と方法 3 が同じ region の出所の判定を通れば、
+規則が 1 つになり、次に方法を足すときもそれを使う。方法 2 を今のまま残し理由を仕様に書く形は、名前を
+明示した利用者が別のグループの region を持ち込む経路を `skip` のグループに残すため採らなかった。
+
+根拠: Value 3 / C3（MVV 版 1）
+
+### 決定 2: `ask` で確認を出さなかったときは、ホストの region を入力の既定の値として見せる
+
+方針が `ask` で鍵の確認を出さない経路（方法 3 でホストに鍵が無い・方法 2）では、region の入力の既定の値に
+ホストの region を出し、どこから来た値かを文に添える（`~/.aws/config の [<節>] から`）。利用者は値と出所を見た
+うえで Enter を押すため、確認を経た取り込みになる。増える質問は、ホストに region があるときの入力の 1 回だけである
+（今はホストに region があると入力を出さずに書く）。y/N の確認を 1 問足す形は、ホストに region が無いときも
+含めて「取り込みますか?」と「region は?」の 2 問を重ね、機密でない値に対して質問がさらに増えるため採らなかった。
+
+根拠: Mission / Value 1（MVV 版 1）
+
+### 決定 3: 方法 3 で鍵の確認を出したときは、その答えを region にも当てる
+
+方法 3 の鍵の確認は「`~/.aws/credentials` の `[default]` の鍵を取り込むか」を尋ねており、同じ `default` の
+プロファイルの region は同じ取り込みの候補に属する。`y` ならホストの region を入力なしで書き（今の `import` と
+同じ）、`N` ならホストの region を読まずに `ap-northeast-1` を既定の値とする入力へ進む。断った利用者に、断った
+プロファイルの region を既定の値として見せると、断った値を Enter 1 回で取り込む形になる。`y` の後に region の
+入力を出す形は、受け入れた候補について 2 度目の確認になるため採らなかった。
+
+根拠: Value 3（MVV 版 1）
+
+### 決定 4: 鍵の確認の結果は aws.py の 3 値で渡し、`HostImport` に記憶させない
+
+鍵の確認は方法 3 の 1 か所でしか起きない。`_collect_access_keys` が確認の結果を `KeyDecision` にして
+`_collect_region` へ引数で渡せば、region の出所の判定は渡された値と方針だけで決まり、テストで値を与えて縛れる。
+`HostImport` に「このステップで既に知らせた・断った」を記憶させて二重の知らせを防ぐ形は、取り込みの場が
+collector の手順の状態を持つことになり、GCP と Git の collector の知らせの振る舞いにも効くため採らなかった。
+`HostImport` の変更は、今の `_skipped` を公開の名前（`notify_skipped`）にすることだけにとどめる。
+
+根拠: Vision（MVV 版 1）
+
+### 決定 5: 参照に region が既にあればそれを残すのは方法 3 だけにし、方法 2 は方針に従って決め直す
+
+要求の退行の条件は「方法 2・方法 3 で `AWS_DEFAULT_REGION` が既に参照にあれば、今と同じくその値を残し、
+ホストを読まない」である。今の方法 3 はそのとおりだが、今の方法 2 は参照の region を見ずに上書きする。
+`env init` で「認証方法を変更しますか?」に `y` と答えると、`AWS_ALL_KEYS` は `AWS_DEFAULT_REGION` を含まないため
+前の方法の region が参照に残る。方法 2 でもそれを残すと、新しく入れたプロファイルの region が書かれず、
+`AWS_DEFAULT_REGION` がプロファイルの節の region より優先されるため、別の region へ向く。
+
+そこで「今と同じく」を採り、region の出所の判定（決定 1）に `keep_existing` を渡す。方法 3 は `True` で判定の
+先頭の「参照に既にある」の枝を通り、方法 2 は `False` でこの枝を通らずに方針の枝で決め直す。方法 2 にも先頭の
+枝を効かせる形は、上の持ち越しを生み、方針が `import` の方法 2 の振る舞い（ホストの region で上書き）も変えて
+要求の「含まない」と重なるため採らなかった。
+
+要求の文（方法 2 を含む）は正である #334 の本文で直し、写しを作り直す。設計の文書の「未確認のまま残ること」に置く。
+
+根拠: Value 2 / Vision（MVV 版 1）
+
+### 決定 6: 正規化と衝突の警告は、取り込む鍵を決めた直後に collector が出す
+
+警告は「この名前で参照へ書く」ことを利用者に知らせるためにある。取り込むと決まった後にだけ出せば、飛ばした
+鍵について出ず（I7）、出すのは collector の 1 か所になる（I6）。アクティブプロファイルの質問より前に出すのは、
+質問が正規化した名前で答えさせるためで、変わった名前を先に見せる。鍵を参照へ書いた後に出す形は、`none` と
+答えて鍵を書かないときに警告が出ない利点があるが、質問の時点で利用者が元のファイル名で答えて尋ね直される
+ため採らなかった。発見の結果に「既に警告したか」を持たせて呼び出しの 2 回目を黙らせる形は、警告を出す場所が
+発見の側に残り、`env sync` だけを打ったときの扱いが別に要るため採らなかった。
+
+根拠: Value 1（MVV 版 1）
+
+### 決定 7: 鍵ファイルの発見を google.py の 1 つにまとめ、sync の引き方を init と同じ規則にそろえる
+
+今の `env._gcp_profile_files` は、`~/gcp-credentials/` を並べ替えずに読み、正規化した名前が衝突すると後に読んだ
+ファイルを採る。`env init` の発見はファイル名の昇順で先のファイルを採る。衝突があると、init が登録した鍵
+ファイルと、控えの更新と sync が引く鍵ファイルが食い違いうる（I9）。発見を `find_credential_files` の 1 つにし、
+`env.py` が結果の `lookup` を使えば、規則が 1 か所に決まり、`_gcp_profile_files` の名前（ファイルの一覧を返す
+ように読めるが、名前から鍵ファイルを引く関数を返す）の不揃い（#310 の項）も同時に消える。衝突の無い場合の
+振る舞いは変わらない。`env.py` の関数を残して中から google.py を呼ぶ形は、引き方の入口が 2 つ残るため採らなかった。
+
+根拠: Vision（MVV 版 1）
+
+### 決定 8: 発見はプロジェクト ID を読まない
+
+今の `env init` の発見は、見つけた鍵ファイルをすべて JSON として読み、プロジェクト ID を取り出す。読めない
+ファイルがあると `Google credentials JSONのパースに失敗` の警告が出る。発見を `env sync` と控えの更新でも使う
+（決定 7）と、今は出ないこの警告が sync でも出るようになる。発見はファイル名と正規化だけを扱い、プロジェクト ID
+は GCP の collector が候補を表示するときに読む。`env init` の出力は今と同じになり、sync の出力も今と同じになる。
+
+根拠: Value 1（MVV 版 1）