NAME

Kelp::Module::Symbiosis - Manage an entire ecosystem of Plack organisms under Kelp

SYNOPSIS

        # in configuration file
        modules => [qw/Symbiosis SomeSymbioticModule/],
        modules_init => {
                Symbiosis => {
                        automount => 0, # boolean, defaults to 1
                },
        },

        # in kelp application
        $kelp->symbiosis->mount('/app-path' => $kelp); # only required if config 'automount' is explicitly false
        $kelp->symbiosis->mount('/other-path' => $kelp->some_symbiotic_module);

        # in psgi script
        my $app = MyApp->new();
        $app->run_all; # instead of run

DESCRIPTION

This module is an attempt to standardize the way many standalone Plack applications should be ran alongside the Kelp framework. The intended use is to introduce new "organisms" into symbiotic interaction by creating Kelp modules that are then attached onto Kelp. Then, the added method run_all should be invoked in place of Kelp's run, which will construct a Plack::App::URLMap and return it as an application.

Why not just use Plack::Builder in a .psgi script?

One reason is not to put too much logic into .psgi script. It my opinion a framework should be capable enough not to make adding an additional application feel like a hack. This is of course subjective.

The main functional reason to use this module is the ability to access the Kelp application instance inside another Plack application. If that application is configurable, it can be configured to call Kelp methods. This way, Kelp can become a glue for multiple standalone Plack applications, the central point of a Plack mixture:

        # in Symbiont's Kelp module (extends Kelp::Module::Symbiosis::Base)

        sub psgi {
                my ($self) = @_;

                my $app = Some::Plack::App->new(
                        on_something => sub {
                                my $kelp = $self->app; # we can access Kelp!
                                $kelp->something_happened;
                        },
                );

                return $app->to_app;
        }

        # in Kelp application class

        sub something_happened {
                ... # handle another app's signal
        }

        sub build {
                my ($kelp) = @_;

                my $another_app = $kelp->get_another_app;
                $kelp->symbiosis->mount('/app' => $another_app);
        }

What can be mounted?

The sole requirement for a module to be mounted into Symbiosis is its ability to run(), returning the psgi application. A module also needs to be a blessed reference, of course. Fun fact: Symbiosis module itself meets that requirements, so one symbiotic app can be mounted inside another.

It can also be just a plain psgi app, which happens to be a code reference.

Whichever it is, it should be a psgi application ready to be ran by the server, wrapped in all the needed middlewares. This is made easier with Kelp::Module::Symbiosis::Base, which allows you to add symbionts in the configuration for Kelp along with the middlewares. Because of this, this should be a preferred way of defining symbionts.

For very simple use cases, this will work though:

        # in application build method
        my $some_app = SomePlackApp->new()->to_app;
        $self->symbiosis->mount('/path', $some_app);

METHODS

mount

        sig: mount($self, $path, $app)

Adds a new $app to the ecosystem under $path.

run_all

        sig: run_all($self)

DEPRECATED: use "run" instead.

run

Constructs and returns a new Plack::App::URLMap with all the mounted modules and Kelp itself.

mounted

        sig: mounted($self)

Returns a hashref containing a list of mounted modules, keyed with their specified mount paths.

METHODS INTRODUCED TO KELP

symbiosis

Returns an instance of this class.

run_all

Shortcut method, same as $kelp->symbiosis->run().

CONFIGURATION

automount

Whether to automatically call mount for the Kelp instance, which will be mounted to root path /. Defaults to 1.

If you set this to 0 you will have to run something like $kelp->symbiosis->mount($mount_path, $kelp); in Kelp's build method. This will allow other paths than root path for the base Kelp application, if needed.

CAVEATS

Routes specified in symbiosis will be matched before routes in Kelp. Once you mount something under /api for example, you will no longer be able to specify Kelp route for anything under /api.

SEE ALSO

• Kelp::Module::Symbiosis::Base, a base for symbiotic modules

• Kelp::Module::Websocket::AnyEvent, a reference symbiotic module

• Plack::App::URLMap, Plack URL mapper application

AUTHOR

Bartosz Jarzyna, <brtastic.dev@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2020 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

cpanm Kelp::Module::Symbiosis

perl -MCPAN -e shell
install Kelp::Module::Symbiosis