serverless-aws-lambda/resources/s3.md

AWS Application Load Balancer and API Gateway - Lambda dev tool for Serverless. Allows Express synthax in handlers. Supports packaging, local invoking and offline ALB, APG, S3, SNS, SQS, DynamoDB Stream server mocking.

## AWS Local S3

### Motivation

Testing AWS Lambda S3 API commands and Notification Events locally.

### Description

This is not a full local implementation of AWS S3.  
However the local S3 server\* supports following requests:

AWS-SDK

- CopyObject
- CreateBucket
- DeleteBucket
- DeleteBucketTagging
- DeleteObject
- DeleteObjects
- DeleteObjectTagging
- GetBucketTagging
- GetObject
- GetObjectTagging
- HeadBucket
- HeadObject
- ListBuckets
- ListObjects
- ListObjectsV2
- PutBucketTagging
- PutObject
- PutObjectTagging

AWS-CLI s3

- cp
- ls
- mb
- mv
- rb
- rm
- sync

AWS-CLI s3api

- copy-object
- create-bucket
- delete-bucket
- delete-bucket-tagging
- delete-object
- delete-objects
- delete-object-tagging
- get-bucket-tagging
- get-object
- get-object-tagging
- head-bucket
- head-object
- list-buckets
- list-objects
- list-objects-v2
- put-bucket-tagging
- put-object
- put-object-tagging

---

supported options:

- prefix
- delimiter
- marker
- start after
- range
- max keys
- continuation token
- metadata
- metadata directive
- content type
- content disposition
- content encoding
- content language
- cache control
- expires
- website redirect location
- storage class
- if match
- if none match
- if modified since
- if unmodified since

\* http://127.0.0.1:PORT/@s3 or http://0.0.0.0:PORT/@s3

### Installation

Import the plugin inside your defineConfig.

```js
// config.js
import { defineConfig } from "serverless-aws-lambda/defineConfig";
import { s3Plugin } from "serverless-aws-lambda/s3";

export default = defineConfig({
  plugins: [s3Plugin()],
});
```

options:

- `localStorageDir`: path to store s3 files locally (default: 'localS3/')
- `persist`: indicates if localStorageDir shoud be persistent (default: true)

---

### Usage example

Subscribe to a S3 event with serverless declaration.

```yaml
# serverless.yml

functions:
  myAwsomeLambda:
    handler: src/myAwsomeLambda.default
    events:
      - s3: myBucket
```

```js
// src/myAwsomeLambda.js

export default async (s3Event) => {
  console.log(s3Event);
};
```

---

### Example of supported S3 declarations

```yaml
- s3: myBucket
```

```yaml
- s3:
    bucket: myBucket
```

```yaml
- s3:
    bucket: myBucket
    event: s3:ObjectCreated:*
```

```yaml
- s3:
    bucket: myBucket
    event: s3:ObjectCreated:Put
    rules:
      - prefix: "images/"
      - suffix: ".jpg"
```

### Example of request with AWS SDK

```ts
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const client = new S3Client({
  region: "eu-west-3",
  endpoint: `http://0.0.0.0:9999/@s3`,
  credentials: {
    // not required if you already have aws config on your OS
    accessKeyId: "fake id",
    secretAccessKey: "fake secret",
  },
});

const Bucket = "myLocalBucket";
const Key = "some/file.json";

const putResponse = await client.send(
  new PutObjectCommand({
    Bucket,
    Key,
    Body: JSON.stringify({ hello: "world" }),
  })
);
console.log(putResponse);
```

### Example with AWS CLI s3

```bash
aws --endpoint-url http://0.0.0.0:9999/@s3 s3 ls
```

### Example with AWS CLI s3api

```bash
aws --endpoint-url http://0.0.0.0:9999/@s3 s3api list-buckets
```