プロバイダーとの約束（版 1）

プロバイダーは、tegata のために 1 種類のシークレットを作り、読み、消す実行ファイルです。tegata は、操作のたびに実行ファイルを 1 回起動し、標準入力に JSON のオブジェクトを 1 つ書き、標準出力から JSON のオブジェクトを 1 つ読みます。標準エラー出力はそのまま利用者に見せるので、プロバイダーはそこに進み具合を書けます（値は決して書かないこと）。

プロバイダーは、どの言語で書いてもかまいません。Rust のプロバイダーは、型と小さな助けのために tegata-plugin のクレートを使えます。

実行ファイルの見つけ方

プロバイダーは、tegata init が source から入れるもの（プロバイダーを入れるとプロバイダーを公開するを見てください）か、command です。

providers:
  cloudflare:
    command: tegata-provider-cloudflare   # relative to the YAML if it has a `/`; otherwise PATH, then next to tegata
    config: { account_id: 0123456789abcdef }
    credentials:
      api_token: { env: TEGATA_CLOUDFLARE_TOKEN, optional: true }

• プロバイダーの config（アカウントの ID など）は、すべての操作に provider_config として渡します。各リソースの config は config として渡します。
• credentials は credentials として渡します。それぞれ環境変数 env から読み、なければ、端末では入力を隠して聞きます（問いは prompt、なければ <provider> <name>）。optional: true なら、ないものは聞かずに外し、どうするかはプロバイダーが決めます（たとえば CLI のログインを使う）。端末の外では、必須の認証情報がなければエラーです。

リクエスト

どのリクエストにも、次のフィールドがあります。

フィールド	説明
protocol	約束の版。今はいつも 1
op	describe、create、read、delete のどれか
type	リソースの種類（api_token など）。describe では空
config	リソースの config
provider_config	プロバイダーの config
credentials	認証情報の名前 → 値の map。決してログに出さないこと
base_dir	YAML のファイルのディレクトリ（config の中の相対のパスのため）
resource	リソースの名前（メッセージのため）

操作

describe

プロバイダーがどの種類に対応しているかを tegata に伝えます。

応答：

{ "types": { "api_token": "managed", "tunnel_token": "managed" }, "replaces": ["tunnel_token"] }

• types：それぞれの種類は managed（tegata が作って消す）か data（tegata は読むだけ）
• replaces（なくてもよい）：値を 1 つしか持てず、新しく作るとすぐに前の値が使えなくなる種類。tegata は、これを作る前に利用者に聞きます。なければ書かないでください

create（managed の種類）

新しい値を作ります。まだ値のないリソースに対して apply が呼び、rotate も呼びます。

応答：

{ "outputs": { "id": "…", "value": "…" }, "state": { "token_id": "…" } }

• outputs：出力の名前 → 値。リソースの secrets が、シークレットの名前とこの出力の名前を対応させます
• state：あとでこの値を消すためにプロバイダーが要るもの（ID、作った時刻）。シークレットの値は決してここに入れないこと：tegata は state を、シークレットの注記にそのままの文字で置きます

read（data の種類）

今の値を読みます。apply が毎回呼びます。

応答：{ "outputs": { … } }

delete（managed の種類）

古い世代が作ったものを消します。prune が呼びます。リクエストには、さらに次があります。

フィールド	説明
state	消す世代のときに create が返した state
current_state	残す、最新の世代の state（なくてもよい。ないときは書かない）。値を 1 つしか持てない種類で役に立つ。たとえば、片付ける前に、古い値をまだ何も使っていないことを確かめる

応答：{}

プロバイダーは、エラーを返して消すのを断ってもかまいません（たとえば、古い値がまだ使われているとき）。そのとき tegata は止まり、メッセージを見せます。

エラー

0 でない終了コードで終わり、標準出力に {"error": "message"} を書きます。メッセージは利用者に見せます。シークレットの値を入れないでください。

互換性

リクエストと応答には、約束の版を変えずにフィールドが足されることがあります。プロバイダーは知らないリクエストのフィールドを無視し、tegata は知らない応答のフィールドを無視します。古いプロバイダーや古い tegata がメッセージを読み違えるような変更をするときは、約束の版を上げます。