view release on metacpan or  search on metacpan

lib/Async/Microservice.pm  view on Meta::CPAN

=head1 NAME

Async::Microservice - Async HTTP Microservice Moose Role

=head1 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!

=head1 DESCRIPTION

This L<Moose::Role> helps quickly bootstrap an async HTTP service that
includes OpenAPI documentation.

See L<https://time.meon.eu/> and the code in L<Async::Microservice::Time>.

=head1 ATTRIBUTES

=head2 static_path

URL path prefix for OpenAPI files. Defaults to C<'static'>. Can be overridden
by passing it to the constructor.

=head2 file_placeholder

Placeholder string used in OpenAPI files (like C<index.html> and C<edit.html>)
that gets replaced with the service name. Defaults to C<'ASYNC-SERVICE-NAME'>.
Useful for templates that need to display the service name dynamically.

=head2 Overriding Predefined Paths

The following paths are provided by default:

=over 4

=item * C</> - Root index (OpenAPI documentation)

=item * C</static/:filename> - OpenAPI files

=item * C</edit> - OpenAPI editor

=item * C</hcheck> - Health check endpoint

=back

You can override any of these default routes by defining them in your
C<get_routes()> method. Your custom routes take precedence over the defaults.

=head2 To bootstrap a new async service

Create a new package for your APIs using the current examples in
C<lib/Async/Microservice/*>. Set the return value of C<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 C<get_routes>.

Copy one of the C<bin/*.psgi> scripts and update it with your new package
name.

Copy one of C<root/static/*.yaml> and rename it to match C<service_name>.

You can now launch the HTTP service with:

    plackup -Ilib --port 8089 --server Twiggy bin/async-microservice-YOURNAME.psgi

In your browser, you can read the OpenAPI documentation:
L<http://0.0.0.0:8089/v1/> and use the editor to extend it:
L<http://0.0.0.0:8089/v1/edit>

=head1 SEE ALSO

OpenAPI Specification: L<https://github.com/OAI/OpenAPI-Specification/tree/master/versions>
or L<https://swagger.io/docs/specification/about/>

L<Async::MicroserviceReq>
L<Twiggy>

=head1 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 moved

=head1 CONTRIBUTORS & 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 L<https://www.apa-it.at/>.

=head1 BUGS

Please report any bugs or feature requests via L<https://github.com/jozef/Async-Microservice/issues>.

=head1 AUTHOR

Jozef Kutej