{"id":22814481,"url":"https://github.com/68publishers/image-storage-lambda","last_synced_at":"2025-03-30T22:16:51.803Z","repository":{"id":56556026,"uuid":"185261213","full_name":"68publishers/image-storage-lambda","owner":"68publishers","description":"🏙 Serverless AWS Lambda service for resizing images on-the-fly","archived":false,"fork":false,"pushed_at":"2023-11-16T19:35:03.000Z","size":171,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-06T02:50:00.775Z","etag":null,"topics":["aws","aws-lambda","image-storage-lambda","lambda","s3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/68publishers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["68publishers"]}},"created_at":"2019-05-06T19:46:29.000Z","updated_at":"2023-08-16T02:32:26.000Z","dependencies_parsed_at":"2022-08-15T20:50:47.411Z","dependency_job_id":null,"html_url":"https://github.com/68publishers/image-storage-lambda","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/68publishers%2Fimage-storage-lambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/68publishers%2Fimage-storage-lambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/68publishers%2Fimage-storage-lambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/68publishers%2Fimage-storage-lambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/68publishers","download_url":"https://codeload.github.com/68publishers/image-storage-lambda/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246385415,"owners_count":20768672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","image-storage-lambda","lambda","s3"],"created_at":"2024-12-12T13:09:05.752Z","updated_at":"2025-03-30T22:16:51.768Z","avatar_url":"https://github.com/68publishers.png","language":"JavaScript","funding_links":["https://github.com/sponsors/68publishers"],"categories":[],"sub_categories":[],"readme":"# Image Storage Lambda\n\nAWS SAM application for generating images on-the-fly based on [sharp](https://github.com/lovell/sharp).\n\nThe concept of an image processing and a configuration is based on our PHP package [68publishers/image-storage](https://github.com/68publishers/image-storage) so this SAM application can be used as an `external` image server for `image-storage`.\nBut the application can be used standalone without `image-storage` of course.\n\n## Requirements\n\n- docker\n- AWS SAM CLI\n\nPlease follow an official Amazon documentation if you don't have the AWS SAM CLI installed already:\n\n- [Installing the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)\n- [Setting Up AWS Credentials](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-set-up-credentials.html)\n\n## Build and Deploy\n\n```bash\n$ make build\n$ make deploy.guided\n```\n\n## Application parameters\n\n#### BasePath\nType: String\n\nDefault: empty string\n\nA base path for cached images. For example if you set this parameter as `foo` then a root directory for all cached images will be `foo`.\n\n#### ModifierSeparator\nType: String\n\nDefault: `,`\n\nA separator for modifier definitions in a path. \nFor example if you set this parameter as `;` then a modifier string in a path will look like this: `w:100;o:auto`.\n\n#### ModifierAssigner\nType: String\n\nDefault: `:`\n\nAn assigner for modifier definitions in a path. \nFor example if you set this parameter as `=` then a modifier string in a path will look like this: `w=100,o=auto`.\n\n#### VersionParameterName\nType: String\n\nDefault: `_v`\n\nA query parameter's name used for a document's version (just for a cache).\n\n#### SignatureParameterName\nType: String\n\nDefault: `_s`\n\nA query parameter's name used for a signature token.\n\n#### SignatureKey\nType: String\n\nDefault: empty string\n\nYour private signature key used for a token encryption. \nSignatures in requests are checked and validated only if this parameter is set.\n\n#### SignatureAlgorithm\nType: String\n\nDefault: `sha256`\n\nAn algorithm used for encryption of signatures (HMAC).\n\n#### AllowedPixelDensity\nType: CommaDelimitedList\n\nDefault: empty string\n\nA comma-separated list with allowed pixel densities - modified `pd`. \nRequests are validated against this list only if the list is not empty. For example `1,2,3`.\n\n#### AllowedResolutions\nType: CommaDelimitedList\n\nDefault: empty string\n\nA comma-separated list with allowed pixel resolutions - modifiers `w` and `h`. \nRequests are validated against this list only if the list is not empty. \nFor example `300x300,300x,x200` allows requests on images with dimensions `300x300` or with `300` width and calculated height or with `200` height and calculated width.\n\n#### AllowedQualities\nType: CommaDelimitedList\n\nDefault: empty string\n\nA comma-separated list with allowed qualities - modifier `q`. \nRequests are validated against this list only if the list is not empty. For example: `80,90,100`.\n\n#### EncodeQuality\nType: Number\n\nDefault: `90`\n\nAn encode quality for cached images.\n\n#### SourceBucketName\nType: String\n\nDefault: `image-storage-source`\n\nA unique Source Bucket's name.\n\n#### CacheBucketName\nType: String\n\nDefault: `image-storage-cache`\n\nA unique Cache Bucket's name.\n\n#### CacheMaxAge\nType: Number\n\nDefault: `31536000`\n\nThe maximum cache age in seconds. The value is used for HTTP headers Cache-Control and Expires.\n\n#### NoImages\nType: CommaDelimitedList\n\nDefault: empty string\n\nNamed paths for no-images in format `name::path`. \nFor example `default::noimage/noapp` is a definition for a default no-image image that is stored as `noimage/noapp`.\n\n#### NoImagePatterns\nType: CommaDelimitedList\n\nDefault: empty string\n\nNamed patterns for no-images in format `name::pattern`. \nor example if you define `user::^userAvatar\\/` and a path of a requested image will match regex then a no-image named `user` will be returned.\n\n## Supported modifiers and image types\n\n#### Modifiers\n\n| Name          | Shortcut | Type            | Note                                                                                                                                                                 | \n|---------------|----------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Original      | original | -               | A modifier without a value, use it if you want to return the original image                                                                                          |\n| Height        | h        | Integer         | Can be restricted by parameter `AllowedResolutions`                                                                                                                  |\n| Width         | w        | Integer         | Can be restricted by parameter `AllowedResolutions`                                                                                                                  |\n| Pixel density | pd       | Integer\\|Float  | Can be restricted by parameter `AllowedPixelDensity`                                                                                                                 |\n| Aspect ratio  | ar       | String          | Required format is `{Int\\|Float}x{Int\\|Float}` and a height or a width (not both) must be also defined. For example `w:200,ar:1x2` is an equivalent of `w:200,h:400` |\n| Fit           | f        | String          | See [supported fits](#supported-fits) for the list of supported values                                                                                               |\n| Orientation   | o        | Integer\\|String | Allowed values are `auto, 0, 90, -90, 180, -180, 270, -270`                                                                                                          |\n| Quality       | q        | Integer         | Can be restricted by parameter `AllowedQualities`                                                                                                                    |\n\n#### Image types\n\n- JPEG - `.jpeg` or `.jpg`\n- Progressive JPEG - `.pjpg`\n- PNG - `.png`\n- GIF - `.gif` (animations support)\n- WEBP - `.webp` (animations support)\n- AVIF - '.avif'\n\n#### Supported fits\n\n- `contain` - Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.\n- `stretch` - Ignore the aspect ratio of the input and stretch to both provided dimensions.\n- `fill` - Preserving aspect ratio, contain within both provided dimensions using \"letterboxing\" where necessary.\n- `crop-*` - Preserving aspect ratio, ensure the image covers both provided dimensions by cropping to fit.\n    - `crop-center`\n    - `crop-left`\n    - `crop-right`\n    - `crop-top`\n    - `crop-top-left`\n    - `crop-top-right`\n    - `crop-bottom`\n    - `crop-bottom-left`\n    - `crop-bottom-right`\n\n## Usage\n\nGenerated images are cached in a Cache Bucket. A name of the Cache Bucket that is defined by parameter `CacheBucketName`. \nIf some image is requested and the Cache Bucket contains it then the image is returned directly. \nOtherwise, a Lambda function is called, and it will try to access the image through the Source Bucket (a name defined by parameter `SourceBucketName`), modify it and save it to the Cache Bucket.\nThe Lambda function can return an error 404 or a `no-image` image if some is provided by you.\n\n#### What is the URL of my API?\n\nAfter the application will be successfully deployed you will see the application's outputs in the console like this:\n\n```shell\nCloudFormation outputs from deployed stack\n----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\nOutputs                                                                                                                                                                                                                                            \n----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n...                                                                                                                                                                                                     \n\nKey                 CacheBucketDistribution                                                                                                                                                                                                        \nDescription         CloudFront URL for cached images - use this URL for image requests                                                                                                                                                             \nValue               https://{HASH}.cloudfront.net                                                                                                                                                                                          \n\n...                                                                                                                                          \n----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n\nSuccessfully created/updated stack - {STACK_NAME} in {REGION}\n```\n\nThe value of key `CacheBucketDistribution` is a host URL for your application.\n\n#### Simple example\n\nFirstly upload any image to the Source Bucket but the name of the object (your image) must be always without a file extension!\nFor example if your image is called `picoftheday.jpeg` and you will drop it to the root of the Source Bucket then you must rename it just to `picoftheday`.\nYour image can be placed into any directory of course.\n\nThen you can try to request some modifications of the image:\n\n```\nhttps://{HASH}.cloudfront.net/original/picoftheday.jpeg - returns the original image\nhttps://{HASH}.cloudfront.net/original/picoftheday.png - returns the original image but in a PNG format\nhttps://{HASH}.cloudfront.net/w:200,h:100,o:90/picoftheday.jpeg - returns an image with dimensions 200x100 and rotated by 90 degrees\nhttps://{HASH}.cloudfront.net/w:200,h:100,pd:2,q:50/picoftheday.jpeg - returns an image with dimensions 400x200 (because of pixel density) and with output quality 50%\n...\nhttps://{HASH}.cloudfront.net/picoftheday.jpeg - an error 500, the URL must always contains an modifiers\nhttps://{HASH}.cloudfront.net/foo/original/bar.jpeg - an error 404, missing object `foo/bar` in the Source Bucket\n```\n\n#### Example with NoImages\n\nThe NoImages are images provided by you that are returned instead of the 404 response if a requested image not found. For example you can configure the parameters `NoImages` and `NoImagePatterns` with this values:\n\n- NoImages - `default::noimage/default,user::noimage/user`\n- NoImagePatterns - `user::^userAvatar\\/`\n\nThen upload any images with names `default` and `user` (without file extensions again) into a directory `noimage` in the Source Bucket. So paths to objects will be `noimage/default` and `noimage/user`\n\nThen you can try to request some nonexistent images:\n\n```\nhttps://{HASH}.cloudfront.net/foo/bar/w:50/baz.jpeg - an image `noimage/default` with 50px width in JPEG format is returned \nhttps://{HASH}.cloudfront.net/user/foo/w:50/bar.png -  an image `noimage/user` with 50px width in PNG format is returned \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F68publishers%2Fimage-storage-lambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F68publishers%2Fimage-storage-lambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F68publishers%2Fimage-storage-lambda/lists"}