Skip to content

feat(infra): add the studuino hex compile lambda (container + http api) - #2278

Merged
smalruby3-editor-bot[bot] merged 5 commits into
developfrom
feat/studuino-hex-lambda-2209
Nov 19, 2026
Merged

smalruby3-editor-bot[bot] merged 5 commits into
developfrom
feat/studuino-hex-lambda-2209

Conversation

@smalruby3-editor-bot

@smalruby3-editor-bot smalruby3-editor-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Refs #2209

なにをしたか

Studuino モードの hex を作る Lambda の土台を、新しい CDK プロジェクト infra/smalruby-studuino-hex として足しました(🧱 infra・追加だけ)。

  • コンテナの Lambda(x86_64・2GB・30 秒): arduino-cli 1.5.1・arduino:avr@1.8.8・Servo 1.2.2・Studuino ライブラリ(5 つ)
  • HTTP API POST /compile: この段階では決まったサンプル(blink / studuino-led)だけをコンパイルして hex を返す(任意の C++ は受け付けない。構文木は feat(infra): hex を作る Lambda に構文木(Studuino IR)の検査と C++ の書き出しを足す #2210)
  • Origin の検査: CORS(infra/shared/cors-origins.ts の resolveCorsOrigins。prod は https://smalruby.app だけ、stg はローカルとブランチプレビューも)+ハンドラでも検査して許可外・Origin なしは 403
  • 上限(env で変えられる): 本文 128KB(413)・IP ごとに 1 分 12 回・1 日 600 回(DynamoDB の固定窓。429 + Retry-After)・コンパイルの打ち切り(504)・API 全体のスロットリング
  • 計測: 1 回ごとに CloudWatch Embedded Metric Format のログを 1 行(時間・本文の大きさ・hex の大きさ・成否・拒否の理由・コールドスタート)。メトリクス Smalruby/StuduinoHex(Requests / Succeeded / Failed / Rejected / CompileTime / HexBytes など)
  • 応答・失敗の形は docs/studuino-mode/README.md(topic/studuino-2163)の「Lambda の API」に合わせた(hex / size / maxSize / source / toolchain、error の名前と HTTP)

決めたこと(AI の推奨)

項目 決めたこと 理由
置き場所 新しい CDK プロジェクト smalruby-studuino-hex コンテナのビルドが重いので、smalruby-api のデプロイを遅くしない。Deploy Infra は cdk.json のあるディレクトリを自動で拾い、bin/sync-worktree-env も infra/*/.env.* を走査するので変更不要
パス POST /compile docs/studuino-mode の「Lambda の API」に合わせた(Issue の /studuino/hex は仮)
ボード アーテック社のボード定義 studuino:avr:studuino(arduino_ide_settings_ver16x_18x.zip の other/hardware/studuino)、上限 15,872 バイト boards.txt は「Studuino (3.3V, 8 MHz) w/ ATmega168」: mcu=atmega168・f_cpu=8000000L・build.board=AVR_PRO・upload は optiboot(arduino・115200bps)・maximum_size=15872。コアとツールは arduino:avr。いまの書きこみ(シグネチャ 1E 94 06・115200bps)とも合う。1.7.x 用は Arduino IDE 1.7(arduino.org 版)向けなので使わない。取れない・sha256 が合わないときは arduino:avr:pro:cpu=8MHzatmega168(上限 14,336)で作り、toolchain.boardError に理由を出す
アーキテクチャ x86_64 avr-gcc と GitHub Actions のランナーに合わせる(arm64 はエミュレーションでビルドが遅い)
コンパイルの打ち切り 既定 25 秒(S12 の目安は 60 秒) API Gateway(HTTP API)の統合は 30 秒で切れる。Lambda も 30 秒にし、その前に 504 を返す。60 秒が要るなら関数 URL への作り直しが要る(下の「確認が要る点」)
版とハッシュ container/third-party.json だけで固定 → CDK が build args で渡す 版を 1 か所で管理。arduino-cli は GitHub リリースの sha256、コア・Servo は arduino-cli が index の checksum で確かめる
ライブラリ https://www.artec-kk.co.jp/studuino/data/studuino_v1_lib.zip(sha256 は人間の手元の studuino_v1_lib.zip と同じ ad0e4aaf…) URL はボード定義と同じ data/ の下と見た推定だったが、stg のコンテナのビルドで取れて sha256 も一致した(応答の toolchain.studuinoLib)。取れない・合わないときはライブラリなしで作り、studuinoLibError に理由を出す(イメージのビルドは止めない)
コンパイルのキャッシュ イメージを作るときにサンプルを 1 回コンパイルしてコアのキャッシュを入れ、起動時に /tmp へ写す コールドスタートでもコアをコンパイルし直さない
IP SHA-256 のハッシュで表に入れる IP をそのまま残さない
DynamoDB の障害 fail-open(通してログに rateLimitFailOpen) rubytee-relay と同じ(.claude/rules/infra/development.md)
カスタムドメイン 付けない(execute-api のエンドポイント) 土台なので最小限。GUI が使う段で必要なら足す

取得元(アーテック社の公式の配布元)

物 URL sha256 stg のビルドで一致
ボード定義(1.6.x/1.8.x 用) https://www.artec-kk.co.jp/studuino/data/arduino_ide_settings_ver16x_18x.zip 7cb02225…084cf ✅
Studuino ライブラリ https://www.artec-kk.co.jp/studuino/data/studuino_v1_lib.zip ad0e4aaf…ee219 ✅

コンテナ(devcontainer の egress firewall)からは artec-kk.co.jp につながらないので、手元の zip(tmp/to-ai-files/studuino/)を scratchpad で展開して中身を確かめた。ファイルはリポジトリにも GitHub にも載せていない(URL と sha256 だけ)。

テスト

  • infra/smalruby-studuino-hex の jest(7 ファイル・79 件): 上限・Origin・回数の窓・応答の形・EMF のメトリクス(policy)、ハンドラ(403 / 413 / 429 / 400 / 422 / 504 / fail-open / base64 / コールドスタート)、スタック(Lambda・ルート・CORS・スロットリング・TTL・ログの保存期間・prod の CORS)、third-party.json
  • npm run build・cdk synth を stg / prod で通した(synth はイメージを作らない)
  • docker が無いのでイメージのビルドはここでは試していない → stg のデプロイで確かめる

stg の結果(commit dd860e95。PR の「🚀 stg にデプロイしました」コメントで確認)

Deploy Infra の [smalruby-studuino-hex] deploy stg は約 3 分(イメージのビルドを含む)で成功した。

コンパイルの時間(サンプルごと・各 2 回)

サンプル 大きさ hex 最初のデプロイ直後のコールド ふつうのコールド ウォーム
blink(コアだけ) 小 1,058 B 11.9 / 12.0 秒(応答 13.5 秒) 2.8 / 3.0 秒(応答 3.8〜4.0 秒) 1.7 / 1.8 秒
studuino-led 小 5,268 B 13.8 / 13.9 秒(応答 15.0〜15.4 秒) 4.7 / 4.8 秒(応答 5.7 秒) 3.4 / 3.5 秒
robot-car 中 10,548 B 13.9 / 14.4 秒(応答 15.4〜15.7 秒) 4.6 / 4.9 秒(応答 5.6〜5.8 秒) 3.5 / 3.5 秒
smalrubot-s1(S1 のファームウェア) 大 12,106 B(上限 15,872 の 76%) 13.7 / 13.8 秒(応答 15.2 秒) 4.9 / 5.1 秒(応答 6.1〜6.3 秒) 3.9 / 4.0 秒
  • 時間は Lambda の中のコンパイル(compileMs)。応答は手元から測った全体の時間。コールドは同時に 8 本送って新しい実行環境で測った(応答の coldStart: true)。
  • 「最初のデプロイ直後」は、新しいスタックに初めてイメージが入った直後の 1 回目(2 回目のデプロイの直後は「ふつうのコールド」の値だった。イメージを初めて読みこむときだけ遅いと見ている)。
  • Lambda の初期化(REPORT の Init Duration)は平均 0.80 秒・最大 0.97 秒。メモリの最大は 425MB(2GB 中。CPU の速さのため 2GB のままにした)。
  • 打ち切り 25 秒は足りる: いちばん遅いのは最初のデプロイ直後の 14.4 秒(応答 15.7 秒)。ふつうのコールドで 5 秒、ウォームで 4 秒。Studuino のフラッシュは 16KB なので、これより大きいプログラムは作れない。
  • 手元(コンテナ)では測れなかった: arduino-cli は GitHub から取れるが、AVR のコアとツール(downloads.arduino.cc)が egress firewall で取れない。

Issue の「テスト」の項目

項目 結果
サンプルの hex が返る ✅ 4 つとも 200(上の表。toolchain にボード定義とライブラリの sha256)
許可外の Origin ✅ 403 forbidden_origin(Origin なしも 403)
本文の上限(130KB を送る) ✅ 413 too_large
回数の上限 ✅ 同じ 1 分の中で 13 回目から 429 rate_limited・Retry-After: 20(その前の計測の呼び出しも同じ窓で数えられている)
ログ ✅ 1 回ごとに event: "studuino_hex_request"(Logs Insights で outcome × coldStart: ok 16・rate_limited 9・invalid_request 5・forbidden_origin 2・too_large 1)
メトリクス ✅ Smalruby/StuduinoHex に Requests / Succeeded / Failed / Rejected / CompileTime / HexBytes / RequestBytes / TotalTime

人間の作業・確認

  • repo Secrets INFRA_STG_DOTENV_SMALRUBY_STUDUINO_HEX・Environment prod の INFRA_PROD_DOTENV_SMALRUBY_STUDUINO_HEX(登録済み)
  • ライブラリ・ボード定義の取得元(上の表。stg のビルドで sha256 が一致)
  • デプロイ用ロールでコンテナのアセット(ECR)を上げられる(stg のデプロイが通った)
  • コンパイルの打ち切りを 25 秒にしたことの了承(API Gateway の 30 秒の制限。計測ではいちばん遅くて 14.4 秒)
  • .claude/rules/infra/development.md の Projects 表と .claude/rules/infra/smalruby-studuino-hex.md(AI は .claude/ を編集しない決まりのため。中身は docs/infra/smalruby-studuino-hex.md を写せばよい)
  • 実機(Studuino)で、返ってきた hex を書きこんで動くか。blink・studuino-led は A0 の LED が 0.5 秒ごとに点滅(8MHz の想定が合っていれば 0.5 秒。16MHz なら 1 秒に見える)。smalrubot-s1 はいまのファームウェアと同じ働き(書きこんだあと通常モードでつながる)
  • .github/workflows/ci-infra.yml の変更(3 ジョブ)のレビュー(Bot の権限外のパス)
  • サンプル smalrubot-s1 は smalruby/smalrubot の sr_studu(MIT、フォルダに LICENSE)を写したもの。Adafruit NeoPixel は同梱せず arduino-cli で 1.15.2 を入れる(元の同梱版より新しい)

🤖 Generated with Claude Code

Add a new CDK project infra/smalruby-studuino-hex: a container Lambda with
arduino-cli, the AVR core and (when the official zip is pinned) the Studuino
library, behind an HTTP API with POST /compile. This stage only compiles
fixed samples (blink / studuino-led).

- Versions and hashes are pinned in container/third-party.json
- Origin check in the handler (403), 128KB body (413), per-IP 12/min and
  600/day in DynamoDB (429), compile cut-off (504)
- One EMF log line per request (Smalruby/StuduinoHex metrics)
- CI jobs in ci-infra.yml, shared CORS copy, docs/infra page

Refs #2209

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@smalruby3-editor-bot smalruby3-editor-bot Bot added 👥 human-review-required Bot 権限外パスを含む PR。本人以外の人間レビュー必須 🧱 infra infra だけの Issue(後方互換のみ・develop へ先行マージ。prod デプロイ後に workflow が閉じる) labels Nov 19, 2026
@github-actions

Copy link
Copy Markdown

🚀 Preview deployed (stg API): https://preview.smalruby.app/feat-studuino-hex-lambda-2209-1de87c4b/

- Board: install Artec's Arduino IDE 1.6.x/1.8.x board definition
  (studuino:avr:studuino, atmega168 8MHz, max 15872 bytes) from the
  official zip, pinned by sha256. Fall back to arduino:avr pro 168 8MHz
  and report boardError if it cannot be fetched or verified.
- Studuino library: pin the sha256 of studuino_v1_lib.zip; the URL is a
  candidate under the same data/ path and is verified by sha256. If it
  fails, build without the library and report studuinoLibError.
- Samples: add robot-car (medium) and smalrubot-s1 (large, the MIT
  sr_studu firmware) to measure compile time; samples may have several
  files. Add Adafruit NeoPixel 1.15.2.
- Response: add coldStart and the board / library errors to toolchain.

Refs #2209

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #2209

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@smalruby3-editor-bot smalruby3-editor-bot Bot added the deploy-stg この PR の infra 変更を stg にデプロイする (#1162) label Nov 19, 2026
@github-actions

Copy link
Copy Markdown

🚀 stg にデプロイしました: smalruby-studuino-hex

項目 値
commit c00f5fee8db04eded4613301883304ff6146705a
branch feat/studuino-hex-lambda-2209
run https://github.com/smalruby/smalruby3-editor/actions/runs/44523589253

stg は共有環境です。この SHA が載っている前提で 動作確認してください。
別の PR があとからデプロイすると上書きされます。

deploy-stg ラベルはこの run の完了時に自動で外れます。もう一度 stg に載せたいときはラベルを付け直してください。

@github-actions github-actions Bot removed the deploy-stg この PR の infra 変更を stg にデプロイする (#1162) label Nov 19, 2026
smalruby3-editor-bot Bot and others added 2 commits November 19, 2026 12:33
Refs #2209

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #2209

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@smalruby3-editor-bot smalruby3-editor-bot Bot added the deploy-stg この PR の infra 変更を stg にデプロイする (#1162) label Nov 19, 2026
@github-actions

Copy link
Copy Markdown

🚀 stg にデプロイしました: smalruby-studuino-hex

項目 値
commit dd860e9545e72e20d1f0189a5bdc1c5999f50c8c
branch feat/studuino-hex-lambda-2209
run https://github.com/smalruby/smalruby3-editor/actions/runs/44525040357

stg は共有環境です。この SHA が載っている前提で 動作確認してください。
別の PR があとからデプロイすると上書きされます。

deploy-stg ラベルはこの run の完了時に自動で外れます。もう一度 stg に載せたいときはラベルを付け直してください。

@github-actions github-actions Bot removed the deploy-stg この PR の infra 変更を stg にデプロイする (#1162) label Nov 19, 2026
@smalruby3-editor-bot
smalruby3-editor-bot Bot merged commit 9c56567 into develop Nov 19, 2026
46 checks passed
@smalruby3-editor-bot
smalruby3-editor-bot Bot deleted the feat/studuino-hex-lambda-2209 branch November 19, 2026 14:32

This branch was previously deployed

1 inactive deployment
stg — dd860e95 Deployed Nov 19, 2026 by smalruby3-editor-bot[bot] via cleanup #454
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

👥 human-review-required Bot 権限外パスを含む PR。本人以外の人間レビュー必須 🧱 infra infra だけの Issue(後方互換のみ・develop へ先行マージ。prod デプロイ後に workflow が閉じる)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants