view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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.psgi

    In 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/

    Async::MicroserviceReq Twiggy

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

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 https://www.apa-it.at/.

BUGS

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

AUTHOR

    Jozef Kutej