Replace the vendor/bin/bref CLI with serverless commands

[mnapoli]

What

This PR aims to remove the vendor/bin/bref CLI and replace it by custom serverless commands.

I'm opening this PR to gather feedback on the idea.

Why

• Simpler commands: the Bref plugin integrates with SF and can then introspect functions, their shortcut names, layers, etc.
  • for example this fixes Simplify bref cli: avoid having to pass the function name #125 (cc @Guillaume-Rossignol)
• Consistent DX: the Bref plugin runs in serverless, so --stage, --region, AWS credentials, etc. will all work the same
• Lighter bref/bref package (because much less Composer dependencies) = faster deploys and faster cold starts for users

How

The Bref plugin already runs in the serverless CLI. I use it to add new serverless commands:

vendor/bin/bref init
# this command is not changed
# it is kept as a small (single-file, no dependencies) standalone CLI in Bref:
vendor/bin/bref init

# Bref CLI https://bref.sh/docs/runtimes/console.html#usage
vendor/bin/bref cli mystack-console-dev
vendor/bin/bref cli mystack-console-dev -- doctrine:migrations:migrate --force
vendor/bin/bref cli mystack-console-dev --region eu-west-1 -- hello # custom region in serverless.yml
# becomes
serverless bref:cli
serverless bref:cli --args="doctrine:migrations:migrate --force"
serverless bref:cli --args="hello" # automatically uses the region/stage of serverless.yml

# Bref local https://bref.sh/docs/function/local-development.html
vendor/bin/bref local hello
vendor/bin/bref local hello '{"name": "Jane"}'
# becomes
serverless bref:local -f hello
serverless bref:local -f hello --data '{"name": "Jane"}'

vendor/bin/bref layers --region eu-west-1
# becomes
serverless bref:layers  # region automatically detected from serverless.yml

TODO

• Reimplement vendor/bin/bref cli
• Reimplement vendor/bin/bref local
• Reimplement vendor/bin/bref layers
• Update docs
• Fix tests
• Reimplement vendor/bin/bref init
• Remove the existing CLI (vendor/bin/bref)
• Document the changes in the Upgrading guide
• Document how to invoke a console function without Serverless Framework
• make bref local work without SF

[soukicz]

Does it mean that I cannot use bref without serverless or that I just have to use longer command?

[aran112000]

Love the idea of moving towards the serverless command style with all but the bref init example, but your BC suggestion sounds a perfect solution to address that

[mnapoli]

@soukicz Bref continues to work with other deployment tools. However these commands won't work unless you use Serverless Framework.

bref local was tied to Serverless Framework anyway. However cli and layers were not. I think the main problem will be for the cli command (layers is a small utility that is not critical).

I will document ways to invoke the console function without using Serverless Framework (using the AWS CLI). Thank you for bringing that up 👍

Also out of curiosity, are you using something else than Serverless Framework?

[soukicz]

Also out of curiosity, are you using something else than Serverless Framework?

It is compliance thing and also training. Serverless adds multiple initial steps and also new software that somebody has to approve. Great thing about lambda+bref is that if somebody needs to make changes to code, they can just run simple docker run - everything just works and no installation is needed.

Serverless is probably great if you are working with it regularly but it is pain for someone that just needs to make quick change and does not care about architecture or setting up special environment for this one project.

Our current quick start readme for bref project looks similar like this:

docker run --rm -it -v ${PWD}:/app composer install
docker run --rm -it --entrypoint= bref/php-80-fpm vendor/bin/bref local --handler=handler.php '{"type": "order.new", "id": "2000212"}'

[mnapoli]

ah ok I see, I forgot about that flow. I'll try to make that available without requiring SF too, it might be possible 👍

[georgeboot]

In the v2 issue, I saw something about a terraform provider. I quite liked that.

How would this proposal affect the terraform deployment options?

[mnapoli]

PR update:

I have documented how to invoke console functions for non-Serverless Framework users (via the AWS CLI): https://github.com/brefphp/bref/blob/cli-to-serverless-plugin/docs/runtimes/console.md#usage-without-serverless-framework

Also, here is how to run bref local for non-Serverless Framework users: https://github.com/brefphp/bref/blob/cli-to-serverless-plugin/docs/function/local-development.md#without-serverless-framework

Let me know if these 2 approaches look OK.

I have also updated vendor/bin/bref init: the command stays the same, we're just dropping the dependency to Symfony Console and making it a standalone (and light) command.

This PR is almost done. We're able to drop 3 dependencies:

• symfony/console (biggest of the 3 by far)
• symfony/filesystem
• symfony/yaml

That doesn't sound like much, but the next step is that I'll be able to extract to separate repositories the built-in Lambda SimpleClient and Websocket SimpleClient. These should have been separate repositories from the start (used by very few users). This will allow us to remove async-aws/lambda and symfony/http-client, which are much bigger.

---

In the v2 issue, I saw something about a terraform provider. I quite liked that.

How would this proposal affect the terraform deployment options?

With the latest changes, all commands can be run without Serverless Framework (though, to be fair, in a less practical way). So that should work out.

[mnapoli]

All documented, let's goooo!

[LorenzoRogai]

Produces:
"More than one function contains the console layer: cannot automatically run it"

How can we specify the right console function on which the command must run?

[mnapoli]

@LorenzoRogai check out #1459

I will be tagging a release shortly.