add documents

Author: intptr-t

LICENSE.md

@@ -0,0 +1,20 @@
+# LICENSE
+
+## under the `docs` directory
+
+[CC-BY 3.0](https://creativecommons.org/licenses/by/3.0/)
+<img src="https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg" alt="CC-BY">
+
+## under the `src` directory
+
+MIT License
+
+```
+Copyright 2021 Tomonori Niwa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

README.md

@@ -0,0 +1,21 @@
+# AWS Lambda Debug
+
+本ドキュメントは、Visual Studio Code, AWS SAM CLI, JavaScript/TypeScriptを使った開発時におけるデバッグ方法の資料です。
+
+ゴールは、AWSが公式に出している[Node.js 12.XのDockerイメージ](https://hub.docker.com/r/amazon/aws-sam-cli-emulation-image-nodejs12.x)を使って、
+SAM(Serverless Application Model)以外のデプロイ環境(例: CDK + TypeScript)でも、SAM CLIを使ってローカルでデバッグできるようになることです。
+
+- [Step 1 環境インストール](./docs/01-installation.md)
+- [Step 2 最小限入門](./docs/02-minimum-getting-started.md)
+- [Step 3 解説とカスタマイズ](./docs/03-instruction-customize.md)
+- [Step 4 環境変数とイベント引数](./docs/04-env-event.md)
+- [Step 5 TypeScriptでデバッグ](./docs/05-typescript.md)
+- [Step 6 CDK + TypeScriptでデバッグ](./docs/06-cdk-typescript.md)
+
+- [トラブルシューティング](./docs/xx-trouble-shoot.md)
+
+## LICENSE
+
+See: [LICENSE.md](./LICENSE.md)
+
+Created by: [intptr-t](https://github.com/intptr-t)

docs/01-installation.md

@@ -0,0 +1,87 @@
+# Step 1 環境準備
+
+## インストール
+それぞれすでにインストール済みの場合はスキップして問題ありません。
+また、使い慣れた代替のツールがある場合そちらを使用しても問題ありません。
+
+### Visual Studio Code
+- <https://code.visualstudio.com/>
+
+コマンドで動作確認
+(※バージョンの値は2021/01/25時点の情報です)
+
+```zsh
+% code -v
+1.52.1
+ea3859d4ba2f3e577a159bc91e3074c5d85c0523
+x64
+```
+
+### Docker Desktop
+- <https://www.docker.com/get-started>
+
+コマンドで動作確認
+(※バージョンの値は2021/01/25時点の情報です)
+
+```zsh
+% docker -v
+Docker version 20.10.2, build 2291f61
+```
+
+### AWS CLI
+- <https://aws.amazon.com/jp/cli/>
+
+コマンドで動作確認
+(※バージョンの値は2021/01/25時点の情報です)
+
+```zsh
+% aws --version
+aws-cli/2.1.8 Python/3.7.4 Darwin/19.6.0 exe/x86_64 prompt/off
+```
+
+### SAM CLIインストール
+- <https://docs.aws.amazon.com/ja_jp/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html>
+
+コマンドで動作確認
+(※バージョンの値は2021/01/25時点の情報です)
+
+```zsh
+% sam --version
+SAM CLI, version 1.15.0
+```
+
+### Git
+- <https://git-scm.com/downloads>
+
+```
+% git --version
+git version 2.24.3 (Apple Git-128)
+```
+
+## 環境設定
+
+- AWS CLI
+
+このドキュメント全体で `local-test` という名称でプロファイルを作成します。
+別の名前で作成した場合、適宜読み替えてください。
+
+```
+% aws configure --profile local-test
+AWS Access Key ID [None]: local-id
+AWS Secret Access Key [None]: local-secret
+Default region name [None]: ap-northeast-1
+Default output format [None]: json
+```
+
+- Docker network
+
+このドキュメント全体で、 `sam-local` という名称でネットワークの設定作成します。
+別の名前で作成した場合は、適宜読み替えてください。
+
+```
+% docker network create sam-local
+```
+
+Back to [README](../README.md)
+
+Next to [Step 2 最小限入門](02-minimum-getting-started.md)

docs/02-minimum-getting-started.md

@@ -0,0 +1,51 @@
+# Step 2 最小限入門
+
+[Step 1 環境準備](./01-installation.md)で設定した環境が設定済みであることを前提に進めます。
+
+## 実行
+
+ターミナル(コマンドプロンプト, PowerShell, bash, zsh, etc.)を立ち上げ、以下コマンドを実行します。
+
+```
+% git clone [email protected]:intptr-t/aws-lambda-local-debug.git
+% cd src/02-1-getting-started
+% code .
+```
+
+Visual Studio Codeが立ち上がったら、`index.js` を開きブレークポイントをセットします。
+
+次に Visual Studio Codeのターミナルを立ち上げます。
+立ち上がったターミナルに以下を貼り付け実行します。
+
+```
+% sam local invoke "test" --template ./template.yaml --docker-network sam-local --no-event --debug-port 5858 --profile local-test
+```
+
+Visual Studio Codeのターミナルに以下の内容が出力されたら、デバッグ開始の準備完了です。
+`F5`キーを入力し、デバッグ実行します。
+
+```
+Debugger listening on ws://0.0.0.0:5858/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+For help, see: https://nodejs.org/en/docs/inspector
+```
+
+実行結果
+
+```
+2021-01-24T18:12:43.649Z	289a5fc1-f44e-4614-8efa-ea443bcfd0eb	INFO	hello, world!
+END RequestId: 289a5fc1-f44e-4614-8efa-ea443bcfd0eb
+REPORT RequestId: 289a5fc1-f44e-4614-8efa-ea443bcfd0eb	Init Duration: 0.82 ms	Duration: 6741.21 ms	Billed Duration: 6800 ms	Memory Size: 128 MB	Max Memory Used: 128 MB	
+null
+```
+
+<img src="./media/02-getting-started.gif" alt="実行結果">
+
+## コマンドの詳細 公式リファレンス
+- [sam local invoke](https://docs.aws.amazon.com/ja_jp/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-invoke.html)
+- [Step-through debugging Lambda functions locally](https://docs.aws.amazon.com/ja_jp/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html)
+
+Prev to [Step 1 環境準備](./01-installation.md)
+
+Back to [README](../README.md)
+
+Next To [Step 3 解説とカスタマイズ](./03-instruction-customize.md)

docs/03-instruction-customize.md

@@ -0,0 +1,82 @@
+# Step 3 解説とカスタマイズ
+
+## 解説
+
+1つ前のステップ[Step 2 最小限入門](./02-minimum-getting-started.md) を解説します。
+
+### index.js
+
+このファイルは、AWS Lambda上で実行したい対象のファイルです。
+今回は、「hello,world!」を出力するだけのプログラムで、何も返却しない(`return`がない)ため結果は null になります。
+
+### template.yaml
+
+sam initでアプリケーションを作成した時の `template.yaml` の代替です。
+`sam local invoke` するのに必要な最低限の設定が記載されたファイルになります。
+値の詳細は [CloudFormation のリファレンス](https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) を参照してください。
+
+公式のドキュメントに無いパラメータとして、
+キモは [AWS CDK側のドキュメント](https://docs.aws.amazon.com/cdk/latest/guide/assets.html#assets_cfn)の記載にある リソースメタデータ `aws:asset:path` です。
+ここに記載されているローカルディレクトリのパスが `sam local invoke` で実行したとき、template.yamlから見て docker上の `/var/task` (LAMBDA_TASK_ROOT) にマウントされるパスになります。
+
+### launch.json
+
+Visual Studio Codeでデバッグするときの構成ファイルです。
+キモは2点、
+1つ目は [Node.js をリモートでデバッグする時の構成](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_remote-debugging)になっていること。
+2つ目は docker上で動いている Lambda 関数をVisual Studio Codeから見たディレクトリへ対応づけるパラメータ `localRoot` を正しく設定することです。
+
+## カスタマイズの例
+
+上記までの内容を総合するとディレクトリ構成をカスタマイズすることが可能になります。
+参考の構成を以下に示します。
+
+詳細は本リポジトリの [03-instruction-customize](../src/03-instruction-customize) を参照してください。
+
+### ディレクトリ構成
+
+- template.yaml を デバッグ専用のディレクトリへ配置
+- index.js を src 配下に配置
+
+```
+.
+├── .vscode
+│   └── launch.json
+├── debug
+│   └── template.yaml
+└── src
+    └── index.js
+```
+
+#### 上記構成のtemplate.yaml
+
+aws:asset:path を template.yaml から見た src ディレクトリを指すようにします。
+(ターミナルのカレントディレクトリ(`.`)では無い点に注意してください)
+
+```yaml
+        aws:asset:path: "../src"
+```
+
+#### 上記構成のlaunch.json
+
+Visual Studio Codeワークスペースルートから見て、src を指すようにします。
+(はじめの解説で開いた ディレクトリ`02-1-getting-started` とは別に `02-2-getting-started-customize` を Visual Studio Codeルートとして開いている点に注意)
+
+```json
+      "localRoot": "${workspaceRoot}/src",
+```
+
+#### 実行コマンド
+
+ターミナルから見て debugディレクトリ配下の template.yaml を指定するため、パスが変更になります。
+(`--template ./debug/template.yaml`の箇所です)
+
+```
+% sam local invoke "test" --template ./debug/template.yaml --docker-network sam-local --no-event --debug-port 5858 --profile local-test
+```
+
+Prev to [Step 2 最小限入門](./02-minimum-getting-started.md)
+
+Back to [README](../README.md)
+
+Next To [Step 4 環境変数とイベント引数](./04-env-event.md)

docs/04-env-event.md

@@ -0,0 +1,42 @@
+# Step 4 環境変数とイベント引数
+
+本節の説明は、SAM CLI の基本的な使い方の内容のため、すでに把握されている方は飛ばして問題ありません。
+
+対象ディレクトリ: [04-env-event](../src/04-env-event)
+
+## 環境変数設定
+
+まず、template.yaml の Resources > _関数名_ > Properties > Environment > Variables に環境変数を追加します。
+これは、AWS Lambda上の環境変数に設定される環境変数に相当します。
+
+ただし、ローカルで実行する際に 認証情報 など秘匿性が高いものを記載するとリポジトリで管理する際に不便になってしまいます。
+そこで、SAM CLIの `---env-vars` で 環境変数を上書きします。
+注意点として、template.yaml に無い環境変数は**上書きできません**。(UPSERTではなく、UPDATE的であるということです。)
+
+## イベント引数
+
+関数が呼び出されたときに渡される引数のJSONファイルを指定します。
+
+### 実行
+
+- `--no-event` から `--event ./debug/debug-event.json` へ変更
+- `--env-vars ./debug/debug-env.json` を追加
+
+```
+% sam local invoke "test" --template ./debug/template.yaml --docker-network sam-local --event ./debug/debug-event.json --env-vars ./debug/debug-env.json --debug-port 5858 --profile local-test
+```
+
+### 実行結果
+
+```
+2021-01-24T20:29:39.502Z        550e5067-c20e-4e63-aa75-68f0561e83ab    INFO    hello,world
+END RequestId: 550e5067-c20e-4e63-aa75-68f0561e83ab
+REPORT RequestId: 550e5067-c20e-4e63-aa75-68f0561e83ab  Init Duration: 0.78 ms  Duration: 3983.27 ms    Billed Duration: 4000 ms Memory Size: 128 MB     Max Memory Used: 128 MB
+"foobar"
+```
+
+Prev to [Step 3 解説とカスタマイズ](./03-instruction-customize.md)
+
+Back to [README](../README.md)
+
+Next to [Step 5 TypeScriptでデバッグ](./05-typescript.md)