NAME
Async::Microservice - Async HTTP Microservice Moose Role
SYNOPSIS
# lib/Async/Microservice/HelloWorld.pm
package Async::Microservice::HelloWorld;
use Moose;
with qw(Async::Microservice);
sub service_name {return 'asmi-helloworld';}
sub get_routes {return ('hello' => {defaults => {GET => 'GET_hello'}});}
sub GET_hello {
my ( $self, $this_req ) = @_;
return [ 200, [], 'Hello world!' ];
}
1;
# bin/async-microservice-helloworld.psgi
use Async::Microservice::HelloWorld;
my $mise = Async::Microservice::HelloWorld->new();
return sub { $mise->plack_handler(@_) };
$ plackup -Ilib --port 8089 --server Twiggy bin/async-microservice-helloworld.psgi
$ curl http://localhost:8089/v1/hello
Hello world!DESCRIPTION
This Moose::Role helps quickly bootstrap an async HTTP service that includes OpenAPI documentation.
See https://time.meon.eu/ and the code in Async::Microservice::Time.
ATTRIBUTES
static_path
URL path prefix for OpenAPI files. Defaults to 'static'. Can be overridden by passing it to the constructor.
file_placeholder
Placeholder string used in OpenAPI files (like index.html and edit.html) that gets replaced with the service name. Defaults to 'ASYNC-SERVICE-NAME'. Useful for templates that need to display the service name dynamically.
Overriding Predefined Paths
The following paths are provided by default:
/- Root index (OpenAPI documentation)/static/:filename- OpenAPI files/edit- OpenAPI editor/hcheck- Health check endpoint
You can override any of these default routes by defining them in your get_routes() method. Your custom routes take precedence over the defaults.
To bootstrap a new async service
Create a new package for your APIs using the current examples in lib/Async/Microservice/*. Set the return value of service_name. This string is used to set the process name and to locate the OpenAPI YAML definition for the documentation. Any GET/POST processing functions must be defined via get_routes.
Copy one of the bin/*.psgi scripts and update it with your new package name.
Copy one of root/static/*.yaml and rename it to match service_name.
You can now launch the HTTP service with:
plackup -Ilib --port 8089 --server Twiggy bin/async-microservice-YOURNAME.psgiIn your browser, you can read the OpenAPI documentation: http://0.0.0.0:8089/v1/ and use the editor to extend it: http://0.0.0.0:8089/v1/edit
SEE ALSO
OpenAPI Specification: https://github.com/OAI/OpenAPI-Specification/tree/master/versions or https://swagger.io/docs/specification/about/
TODO
- graceful termination (finish all requests before terminating on sigterm/hup)
- systemd service file examples
- static/index.html and static/edit.html are not really static, should be movedCONTRIBUTORS & CREDITS
The following people have contributed to this distribution by committing their code, sending patches, reporting bugs, asking questions, suggesting useful advice, nitpicking, chatting on IRC or commenting on my blog (in no particular order):
AI
you?Also thanks to my current day-job-employer https://www.apa-it.at/.
BUGS
Please report any bugs or feature requests via https://github.com/jozef/Async-Microservice/issues.
AUTHOR
Jozef Kutej
COPYRIGHT & LICENSE
Copyright 2020 Jozef Kutej, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.