The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


        # in configuration file
        modules => [qw/Symbiosis SomeSymbioticModule/],
        modules_init => {
                Symbiosis => {
                        mount => '/kelp', # a path to mount Kelp main instance
                SomeSymbioticModule => {
                        mount => '/elsewhere', # a path to mount SomeSymbioticModule

        # in kelp application - can be skipped if all mount paths are specified in config above
        my $symbiosis = $kelp->symbiosis;
        $symbiosis->mount('/app-path' => $kelp);
        $symbiosis->mount('/other-path' => $kelp->module_method);
        $symbiosis->mount('/other-path' => 'module_name'); # alternative - finds a module by name

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


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.


Starting from version 2.00, this module is no longer just a syntax sugar for Plack::App::URLMap. It offers the new KelpX::Symbiosis is a base class for your Kelp application, which routes all traffic through the Kelp router. This means you can freely mix and match your own Kelp code with plack applications and middlewares. See its documentation for details.

Both Kelp::Module::Symbiosis and KelpX::Symbiosis have their use cases, use the one which suits you best.

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!

                return $app->to_app;

        # in Kelp application class

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

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);



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

Adds a new $app to the ecosystem under $path. $app can be:

  • A blessed reference - will try to call run on it

  • A code reference - will try calling it

  • A string - will try finding a symbiotic module with that name and mounting it. See "name" in Kelp::Module::Symbiosis::Base


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

Note: it will not run mounted object twice. This means that it is safe to mount something in two paths at once, and it will just be an alias to the same application.


        sig: mounted($self)

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


        sig: loaded($self)

new in 1.10

Returns a hashref containing a list of loaded modules, keyed by their names.

A module is loaded once it is added to Kelp configuration. This can be used to access a module that does not introduce new methods to Kelp.



Returns an instance of this class.


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


        # Symbiosis MUST be specified as the first one
        modules => [qw/Symbiosis Module::Some/],
        modules_init => {
                Symbiosis => {
                        mount => '/kelp',
                'Module::Some' => {
                        mount => '/some',

Symbiosis should be the first of the symbiotic modules specified in your Kelp configuration. Failure to meet this requirement will cause your application to crash immediately.


new in 1.10

A path to mount the Kelp instance, which defaults to '/'. Specify a string if you wish a to use different path. Specify an undef or empty string to avoid mounting at all - you will have to run something like $kelp->symbiosis->mount($mount_path, $kelp); in Kelp's build method.


new in 1.11

A boolean flag (1/0) which enables reverse proxy for all the Plack apps at once. Requires Plack::Middleware::ReverseProxy to be installed.

middleware, middleware_init

new in 1.12

Middleware specs for the entire ecosystem. Every application mounted in Symbiosis will be wrapped in these middleware. They are configured exactly the same as middlewares in Kelp. Regular Kelp middleware will be used just for the Kelp application, so if you want to wrap all symbionts at once, this is the place to do it.


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.



Bartosz Jarzyna, <>


Copyright (C) 2020 - 2024 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.