Merge pull request #11 from michimani/release/0.1.0

release v0.1.0

CHANGELOG_DEV.md

@@ -0,0 +1,12 @@
+CHANGELOG for DEV
+===
+This is a version of CHANGELOG less than v1.0.0
+
+## [Unreleased]
+
+TBD
+
+v0.1.0 (2022-12-05)
+====
+
+* dev release 🚀

README.md

@@ -8,10 +8,88 @@ This is a Extension for AWS Lambda Function that records history of invocation a
 - Records in memory the AWS Request IDs of Lambda functions invoked at the same runtime execution environment along with the time of the invocation.
 - Listen on localhost (default port: 1203) for an http server that returns a list of invocations executed up to that point.
 
+# Usage
 
-# Example
+## Download or build extension's binary file
 
-See [_example](https://github.com/michimani/invocation-history-extension/tree/main/_example) for using this extension at the Lambda Function using container image.
+First, prepare the binary file of the extension.  
+You can either download it by specifying a released version, or clone this repository and build it on your end.
+
+### Download extension binary from released assets
+
+You can obtain pre-built extensions in zip format at the following URL.
+
+```bash
+https://github.com/michimani/invocation-history-extension/releases/download/${EXTENSION_VERSION}/extension.zip
+```
+
+Please click [here](https://github.com/michimani/invocation-history-extension/releases) to check the released versions.
+
+### Build extension yourself
+
+Cloning this repository and executing the following command will build the extension and generate `extension.zip` under the `bin` directory.
+
+```bash
+make build
+```
+
+## Use extension in your Lambda Function
+
+This extension can be used in Lambda functions by deploying the extension as a Lambda Layer or by including a binary file in the container image.
+
+### As the Lambda Layer
+
+To use this extension as a Lambda Layer, execute the following AWS CLI (v2) command to publish a Lambda Layer.
+
+```bash
+aws lambda publish-layer-version \
+--layer-name "invocation-history-extension" \
+--zip-file  "fileb://extension.zip" \
+--region <your region>
+```
+
+Then, use the `update-function-configuration` command to specify the value of `LayerVersionArn` to the Lambda function that wants to use this extension.
+
+### Include in container image
+
+Prepare a Dockerfile like the following and place the binary files of the extension in the `/opt/extensions` directory in the image.
+
+```dockerfile
+FROM public.ecr.aws/lambda/provided:al2 as build
+ENV EXTENSION_VERSION 0.1.0
+RUN yum install -y golang unzip
+RUN go env -w GOPROXY=direct
+ADD go.mod go.sum ./
+RUN go mod download
+ADD . .
+RUN go build -o /main
+RUN mkdir -p /opt
+ADD ./extension.zip ./
+RUN unzip extension.zip -d /opt
+RUN rm extension.zip
+
+FROM public.ecr.aws/lambda/provided:al2
+COPY --from=build /main /main
+COPY entry.sh /
+RUN chmod 755 /entry.sh
+RUN mkdir -p /opt/extensions
+WORKDIR /opt/extensions
+COPY --from=build /opt/extensions .
+ENTRYPOINT [ "/entry.sh" ]
+CMD ["/main"]
+```
+
+# IPC (Inter-Process Communication)
+
+This extension starts an HTTP API server on runtime, listening on `localhost:1203`. You can call `GET /invocations` to get a list of AWS Request IDs of functions invoked in the same runtime environment (including currently running ones).
+
+The port number can be changed by setting the environment variable `INVOCATION_HISTORY_EXTENSION_HTTP_PORT` to any value. The default is `1203`.
+
+Please see [here](https://github.com/michimani/invocation-history-extension/tree/main/docs/ipc.yaml) for API server specs.
+
+# Example for using this extension
+
+See [_example](https://github.com/michimani/invocation-history-extension/tree/main/_example) for using this extension at the Lambda Function (Golang) using container image.
 
 # License
 

_example/Dockerfile

@@ -1,12 +1,13 @@
 FROM public.ecr.aws/lambda/provided:al2 as build
+ENV EXTENSION_VERSION 0.1.0
 RUN yum install -y golang unzip
 RUN go env -w GOPROXY=direct
 ADD go.mod go.sum ./
 RUN go mod download
 ADD . .
 RUN go build -o /main
 RUN mkdir -p /opt
-ADD ./bin/extension.zip ./
+ADD https://github.com/michimani/invocation-history-extension/releases/download/v$EXTENSION_VERSION/extension.zip ./
 RUN unzip extension.zip -d /opt
 RUN rm extension.zip
 

docs/ipc.yaml

@@ -0,0 +1,68 @@
+# This document describes Invocation History Extension for AWS Lambda API using the OpenAPI 3.0 specification.
+
+openapi: 3.0.0
+info:
+  title: Invocation History Extension's IPC
+  description: Invocation History Extension's IPC is an HTTP API for getting invocation history.
+  version: 0.1.0
+
+servers:
+  - url: https://example.com:1203
+
+paths:
+
+  /invocations:
+    get:
+      summary: >
+        List of invocations that invocated on the same runtime environment.
+      responses:
+        '200':
+          description: >
+            List of invocations.
+          content:
+            application/json:
+              schema:
+                - $ref: '#/components/schemas/InvocationsResponse'
+        '500':
+          description: >
+            Internal server error.
+
+components:
+  schemas:
+    InvocationsResponse:
+      type: object
+      properties:
+        invocations:
+          type: array
+          items:
+            $ref: '#/components/schemas/Invocations'
+      example:
+        {
+          'invocations': [
+            {
+              'awsRequestId': '95a49622-a910-4113-a061-04a22f7662a4',
+              'invocatedAt': '2022-12-04T00:15:03.255782173Z'
+            },
+            {
+              'awsRequestId': 'e6ea52db-0f97-4961-9974-4513c783c397',
+              'invocatedAt': '2022-12-04T00:15:05.756475067Z'
+            },
+            {
+              'awsRequestId': '7824be6b-3176-43fb-84ec-3b7e6d788378',
+              'invocatedAt': '2022-12-04T00:15:06.992783032Z'
+            }
+          ]
+        }
+
+    Invocations:
+      type: object
+      properties:
+        awsRequestId:
+          type: string
+        invocatedAt:
+          type: string
+      example:
+        {
+          awsRequestId: '88ed8648-5905-404c-aac4-30bb82ae14af',
+          invocatedAt: '2022-12-05T13:22:37.451851551Z'
+        }