libsacloud v2 Design Proposal

[yamamoto-febc]

Overview

Background

現状のlibsacloudには次のような課題がある。

• データモデルの階層が深く、テストなどで手動でデータ生成するのが面倒
• sacloudパッケージのデータモデルで構造体リテラルが利用できない
• IaaS APIクライアントにてcontext/Contextを受け取れないなどGolangらしくない
• saklient互換のFluent APIを採用しているがGolangらしくなくテスト用のインターフェースが作成しにくい面がある
• NULL/空文字の区別がなく、値の未指定なのか空の値をセットしたいのか区別できないことがある

これらを解決するため、libsacloud v2として再設計/再実装する。

Design Goals

• saklient互換性を廃し、よりGolangらしいモダンなスタイルを採用
• Declarative approachにより網羅的な実装と柔軟性を両立させる
• クライアント側にIaaS APIデータモデルに依存しないフラットなデータモデルを提供する
• 現行のbuilderパッケージやutilsパッケージなどで提供している高レベル操作を引き続きサポートする
• API呼び出しで一貫したCRUD方針を採用/実現する(例: CREATE操作の冪等性の担保など)

Non-Goals

• 後方互換性の維持

Features

Layered Models

• モデル層をIaaSと1:1に対応する層(IaaS Layer)とクライアント側に公開するフラットな構造を持つ層(Core Domain Layer)の2層に分ける
• 両層を結ぶマッピングを実装し、相互に変換可能にする
• Core Domain LayerはIaaS Layerが持つモデルの属性に加え、クライアント側に公開すべき操作をメソッドとして実装する。
  (クライアント側が意識する必要のない部分については属性のみを提供する)
• 両層ともコード生成を駆使することでインターフェースレベルで互換性を持たせる

libsacloudのクライアントは基本的にCore Domain Layerのモデルを操作する。
ただし、例外的にIaaS Layerを直接操作する手段も提供する。

Declarative Approach

• モデルの定義にProtocol Buffersを採用し、コード生成でモデルの基本的な実装を行う
• 特に前述のモデル実装は同様のメソッドが多数のモデルに共通して必要となる場面が多いため、コード生成を基本とする
• 高レベル操作を手動で実装する部分もあるため、コード生成はGeneration Gapを考慮する

IaaS API

• リクエスト/レスポンス共にパラメータをDeclarative Approachで実装する
• CRUD操作それぞれのパラメータを個別に定義する
  (現行はIaaSのデータモデルを直接指定する必要があり、更新可否や必須の値の判断などが困難)
• CRUDでの冪等性のサポート
  https://github.com/Azure/azure-cli/blob/dev/doc/command_guidelines.md#standard-command-types
  • 現行のIaaS APIではslugが存在しないため、CREATE時はNameなどを擬似slugとして扱う

[yamamoto-febc]

設計の際のボトムアップな作業(仮実装)などを以下に置く。
https://github.com/sacloud/libsacloud-v2

[yamamoto-febc]

• 単一リソースに対するCRUDのテストコード生成
• テスト用APIサーバのコード生成

[yamamoto-febc]

v2の開発開始に伴いクローズとする。

• 基本的にはDesign Goals/Featuresを踏まえていく
• API呼び出しで一貫したCRUD方針を採用/実現する(例: CREATE操作の冪等性の担保など)についてはv2.0時点では対応しない(対応しないが高レベルAPIで対応できる余地を残しておきたい)
• v2の開発がある程度落ち着いたらこのIssueの内容をdocs配下にドキュメント化する