Merge pull request #1069 from brefphp/improve-case-when-region-doesnt…

…-exist

Improve error messages and docs when a region is not supported

docs/runtimes/README.md

@@ -23,15 +23,15 @@ Bref provides 2 main runtimes:
 
 You can see in the documentation menu how these two runtimes are used for two different kinds of applications.
 
-### Web apps: `php-74-fpm` and `php-73-fpm`
+### Web apps: `php-80-fpm` and `php-74-fpm`
 
 This runtime uses PHP-FPM to run **web applications** on AWS Lambda.
 
 It's **the easiest to start with**: it works like traditional PHP hosting and is compatible with Symfony and Laravel.
 
 [Get started with the FPM runtime in "Bref for web apps"](/docs/runtimes/http.md).
 
-### Event-driven functions: `php-74` and `php-73`
+### Event-driven functions: `php-80` and `php-74`
 
 AWS Lambda was initially created to run _functions_ (yes, functions of code) in the cloud.
 
@@ -64,9 +64,9 @@ functions:
     hello:
         ...
         layers:
-            - ${bref:layer.php-74}
+            - ${bref:layer.php-80}
             # or:
-            - ${bref:layer.php-74-fpm}
+            - ${bref:layer.php-80-fpm}
 ```
 
 The `${...}` notation is the [syntax to use variables](https://serverless.com/framework/docs/providers/aws/guide/variables/) in `serverless.yml`. Bref provides a serverless plugin ("`./vendor/bref/bref`") that provides those variables:
@@ -99,9 +99,12 @@ The layer names follow this pattern:
 
 ```
 arn:aws:lambda:<region>:209497400698:layer:<layer-name>:<layer-version>
+
+For example:
+arn:aws:lambda:us-east-1:209497400698:layer:php-80:21
 ```
 
-To use them manually you need to use that full name. For example in `serverless.yml`:
+You can use layers via their full ARN, or example in `serverless.yml`:
 
 ```yaml
 service: app
@@ -112,7 +115,7 @@ functions:
     hello:
         ...
         layers:
-            - 'arn:aws:lambda:us-east-1:209497400698:layer:php-73:7'
+            - 'arn:aws:lambda:us-east-1:209497400698:layer:php-80:21'
 ```
 
 Or if you are using [SAM's `template.yaml`](https://aws.amazon.com/serverless/sam/):
@@ -127,7 +130,7 @@ Resources:
             ...
             Runtime: provided.al2
             Layers:
-                - 'arn:aws:lambda:us-east-1:209497400698:layer:php-73:7'
+                - 'arn:aws:lambda:us-east-1:209497400698:layer:php-80:21'
 ```
 
 Bref layers work with AWS Lambda regardless of the tool you use to deploy your application: Serverless, SAM, CloudFormation, Terraform, AWS CDK, etc.
@@ -140,6 +143,8 @@ The latest of runtime versions can be found at [runtimes.bref.sh](https://runtim
 
 <iframe src="https://runtimes.bref.sh/embedded" class="w-full h-96"></iframe>
 
+**Watch out:** if you use the layer ARN directly instead of the `${bref:layer.php-80}` variables (which only work in `serverless.yml`), you may need to update the ARN (the `<version>` part) when you update Bref. Follow the Bref release notes closely.
+
 ### Bref ping
 
 Bref layers send a ping to estimate the total number of Lambda invocations powered by Bref. That statistic is useful in two ways:

index.js

@@ -32,15 +32,15 @@ class ServerlessPlugin {
                     const region = options.region || await resolveConfigurationProperty(['provider', 'region']);
 
                     if (!address.startsWith('layer.')) {
-                        throw new Error(`Unknown Bref variable \${bref:${address}}, the only supported syntax right now is \${bref:layer.XXX}`);
+                        throw new serverless.classes.Error(`Unknown Bref variable \${bref:${address}}, the only supported syntax right now is \${bref:layer.XXX}`);
                     }
 
                     const layerName = address.substr('layer.'.length);
                     if (! (layerName in layers)) {
-                        throw new Error(`Unknown Bref layer named "${layerName}"`);
+                        throw new serverless.classes.Error(`Unknown Bref layer named "${layerName}".\nIs that a typo? Check out https://bref.sh/docs/runtimes/ to see the correct name of Bref layers.`);
                     }
                     if (! (region in layers[layerName])) {
-                        throw new Error(`There is no Bref layer named "${layerName}" in region "${region}"`);
+                        throw new serverless.classes.Error(`There is no Bref layer named "${layerName}" in region "${region}".\nThat region may not be supported yet. Check out https://runtimes.bref.sh to see the list of supported regions.\nOpen an issue to ask for that region to be supported: https://github.com/brefphp/bref/issues`);
                     }
                     const version = layers[layerName][region];
                     return {
@@ -59,10 +59,10 @@ class ServerlessPlugin {
                 const region = this.provider.getRegion();
                 const layerName = variableString.substr('bref:layer.'.length);
                 if (! (layerName in layers)) {
-                    throw `Unknown Bref layer named "${layerName}"`;
+                    throw new serverless.classes.Error(`Unknown Bref layer named "${layerName}".\nIs that a typo? Check out https://bref.sh/docs/runtimes/ to see the correct name of Bref layers.`);
                 }
                 if (! (region in layers[layerName])) {
-                    throw `There is no Bref layer named "${layerName}" in region "${region}"`;
+                    throw new serverless.classes.Error(`There is no Bref layer named "${layerName}" in region "${region}".\nThat region may not be supported yet. Check out https://runtimes.bref.sh to see the list of supported regions.\nOpen an issue to ask for that region to be supported: https://github.com/brefphp/bref/issues`);
                 }
                 const version = layers[layerName][region];
                 return `arn:aws:lambda:${region}:209497400698:layer:${layerName}:${version}`;