sgnix / kelp

A web framework light, yet rich in nutrients.

A web framework light, yet rich in nutrients

Kelp is a Perl web framework focused on Plack application toolkit. It's lean, fast and extensible.

Installation

Kelp is distributed through CPAN. It can be installed through a local CPAN client, for example:

cpanm Kelp

Documentation

The Kelp manual can be viewed either online on metacpan or offline by running a perldoc Kelp::Manual command. For detailed information, consult documentation pages for specific parts of Kelp.

Bugs and feature requests

Please use the Github's issue tracker to file both bugs and feature requests.

Contributions

Contributions to the project in form of Github's pull requests are welcome. Please make sure your code is in line with the general coding style of the module. Let us know via a github issue if you plan something bigger so we can talk it through.

Author

Stefan Geneshky

Contributors

In no particular order:

Julio Fraire

Maurice Aubrey

David Steinbrunner

Gurunandan Bhat

Perlover

Ruslan Zakirov

Christian Froemmel (senfomat)

Ivan Baidakou (basiliscos)

roy-tate

Konstantin Yakunin (@yakunink)

Benjamin Hengst (notbenh)

Nikolay Mishin (@mishin)

Bartosz Jarzyna (bbrtj)

License

This module and all the modules in this package are governed by the same license as Perl itself.

kelp's Issues

Default value for 'opts' can not be a reference. at /usr/local/share/perl/5.18.2/Kelp/Base.pm line 41.

What I do wrong?
cat test.t
use Kelp::Base;

attr source => 'dbi:mysql:users';
attr user   => 'test';
attr pass   => 'secret';
attr opts   => { PrintError => 1, RaiseError => 1 };

perl test.t
Default value for 'opts' can not be a reference. at /usr/local/share/perl/5.18.2/Kelp/Base.pm line 41.
Kelp::Base::attr('main', 'opts', 'HASH(0x9458d8)') called at /usr/local/share/perl/5.18.2/Kelp/Base.pm line 26
Kelp::Base::ANON('opts', 'HASH(0x9458d8)') called at test.t line 6

Bridges report unknown status in top level stanza

When attempting to access the bridged routes an error occurs:

missing status at /home/zef/perl5/perlbrew/perls/perl-5.16.3/lib/site_perl/5.16.3  /Kelp.pm line 195.
at /home/zef/perl5/perlbrew/perls/perl-5.16.3/lib/5.16.3/Carp.pm line 100

My routes:

# Admin
$r->add(
    '/admin/staticpage/' => {
        to   => 'Admin::StaticPage::list',
        tree => [
            '/edit' => {
                to      => 'Admin::StaticPage::edit',
            }
        ]
    }
);

My controller:

package Bastille::BMS::Admin::StaticPage;
use Kelp::Base 'Kelp';

# VERSION

sub list {
my $self = shift;
$self->template('admin/staticpages');
}

sub edit {
my $self = shift;
$self->template('admin/staticpage_edit')

}


'static page administration';

Ive tried to minimalize the routes/controller to the bare minimum. Also these routes work independently of each other. I've looked through the existing test to see if I'm missing anything for trees and couldnt see a discrepancy.

Thanks!
Adam

I don't understand this example

Line 583 & 583

https://github.com/naturalist/kelp/blob/master/lib/Kelp/Routes.pm#L583
https://github.com/naturalist/kelp/blob/master/lib/Kelp/Routes.pm#L584

I didn't understand the meaning of these two examples.
I think these lines are exactly identical ;-)

request and response attributes to define package names rather than overwrite build_*

Currently Kelp encourage's customers to overwrite methods just to change the class that is used in build_request and build_response. It seems that this would be a great use of an attribute that can be leveraged in this case.

make test fails in Kelp-0.3102

In the current Kelp-0.3102-Release on CPAN the test-Commands fails. I think it is an utf-8 issue. When this is an utf8-problem within my terminal, what is the workaround?

The output of make and make test:

[senfomat@duesentrieb] ~/Development/tmp/Kelp-0.3102> make
cp lib/Kelp/Module/Config/Null.pm blib/lib/Kelp/Module/Config/Null.pm
cp lib/Kelp/Module/Config.pm blib/lib/Kelp/Module/Config.pm
cp lib/Kelp/Module/Routes.pm blib/lib/Kelp/Module/Routes.pm
cp lib/Kelp/Base.pm blib/lib/Kelp/Base.pm
cp lib/Kelp/Module/Template.pm blib/lib/Kelp/Module/Template.pm
cp lib/Kelp/Request.pm blib/lib/Kelp/Request.pm
cp lib/Kelp/Module/Template/Null.pm blib/lib/Kelp/Module/Template/Null.pm
cp lib/Kelp/Routes.pm blib/lib/Kelp/Routes.pm
cp lib/Kelp/Module/JSON.pm blib/lib/Kelp/Module/JSON.pm
cp lib/Kelp/Response.pm blib/lib/Kelp/Response.pm
cp lib/Kelp/Test.pm blib/lib/Kelp/Test.pm
cp lib/Kelp/Module.pm blib/lib/Kelp/Module.pm
cp lib/Kelp/Module/Null.pm blib/lib/Kelp/Module/Null.pm
cp lib/Kelp/Routes/Pattern.pm blib/lib/Kelp/Routes/Pattern.pm
cp lib/Kelp/Template.pm blib/lib/Kelp/Template.pm
cp lib/Kelp/Module/Logger.pm blib/lib/Kelp/Module/Logger.pm
cp lib/Kelp/Less.pm blib/lib/Kelp/Less.pm
cp lib/Kelp.pm blib/lib/Kelp.pm
cp bin/Kelp blib/script/Kelp
/opt/local/bin/perl5.16 -MExtUtils::MY -e 'MY->fixin(shift)' -- blib/script/Kelp
Manifying blib/man3/Kelp::Response.3pm
Manifying blib/man3/Kelp::Test.3pm
Manifying blib/man3/Kelp::Module::Config.3pm
Manifying blib/man3/Kelp::Module.3pm
Manifying blib/man3/Kelp::Base.3pm
Manifying blib/man3/Kelp::Routes::Pattern.3pm
Manifying blib/man3/Kelp::Request.3pm
Manifying blib/man3/Kelp::Template.3pm
Manifying blib/man3/Kelp::Module::Template.3pm
Manifying blib/man3/Kelp::Routes.3pm
Manifying blib/man3/Kelp::Module::JSON.3pm
Manifying blib/man3/Kelp::Less.3pm
Manifying blib/man3/Kelp.3pm

[senfomat@duesentrieb] ~/Development/tmp/Kelp-0.3102> make test
PERL_DL_NONLAZY=1 /opt/local/bin/perl5.16 "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/base.t .................. ok
t/bin_tests.t ............. ok
t/less.t .................. ok
t/middleware.t ............ ok
t/module.t ................ ok
t/module_config.t ......... ok
t/module_config_get.t ..... ok
t/module_config_merge.t ... ok
t/module_config_null.t .... ok
t/module_json.t ........... ok
t/module_load.t ........... ok
t/module_logger.t ......... ok
t/module_template.t ....... 1/?
#   Failed test at t/module_template.t line 22.
Wide character in print at /opt/local/lib/perl5/vendor_perl/5.16.1/Test/Builder.pm line 1759.
#                   'Hello, world! �
# '
#     doesn't match '(?^u:Hello, world! ☃)'

#   Failed test at t/module_template.t line 23.
Wide character in print at /opt/local/lib/perl5/vendor_perl/5.16.1/Test/Builder.pm line 1759.
#                   'Hello, world! �
# '
#     doesn't match '(?^u:Hello, world! ☃)'
# Looks like you failed 2 tests of 5.
t/module_template.t ....... Dubious, test returned 2 (wstat 512, 0x200)
Failed 2/5 subtests
t/module_template_null.t .. ok
t/pattern_build.t ......... ok
t/pattern_cache.t ......... ok
t/pattern_match.t ......... ok
t/release-pod-syntax.t .... skipped: these tests are for release candidate testing
t/request.t ............... ok
t/response.t .............. ok
t/response_finalize.t ..... ok
t/routes_add.t ............ ok
t/routes_camelize.t ....... ok
t/routes_match.t .......... ok
t/routes_url.t ............ ok
t/run.t ................... ok
t/run_bridge.t ............ ok
t/run_panic.t ............. ok
t/subclassed.t ............ ok
t/template.t .............. 1/?
#   Failed test 'Render file'
#   at t/template.t line 9.
Wide character in print at /opt/local/lib/perl5/vendor_perl/5.16.1/Test/Builder.pm line 1759.
#                   'Hello, world! �
# '
#     doesn't match '(?^u:Hello, world! ☃)'
# Looks like you failed 1 test of 4.
t/template.t .............. Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/4 subtests
t/test_psgi.t ............. ok

Test Summary Report
-------------------
t/module_template.t     (Wstat: 512 Tests: 5 Failed: 2)
  Failed tests:  4-5
  Non-zero exit status: 2
t/template.t            (Wstat: 256 Tests: 4 Failed: 1)
  Failed test:  2
  Non-zero exit status: 1
Files=31, Tests=560,  4 wallclock secs ( 0.17 usr  0.06 sys +  3.05 cusr  0.30 csys =  3.58 CPU)
Result: FAIL
Failed 2/31 test programs. 3/560 subtests failed.
make: *** [test_dynamic] Error 255

Proposal: Path::Tiny instead of File::Slurp

Hi Stefan,

File::Slurp is used in only one place in Kelp script. File::Slurp has some problems: it fails in 5.30 and current dev Perls, and also in older Perls on some systems like Haiku or Windows.

Path::Tiny has the necessary functionality and doesn't suffer from File::Slurp problems. Path::Tiny is very likely to be already installed as a prerequisite for some other popular modules like Carton, Dist::Zilla, or tidyall.

Kelp::Less cannot encode JSON on its own

Hello, thank you for this piece of software.
In Kelp.pm pod, section Quick development using Kelp::Less an example is given that is supposed to encode JSON, however for me it doesn't. Instead it throws an exception that no JSON decoder is available.
After some digging it seems a line is missing in the example: module 'JSON'; that will load JSON encoder module into the app. Can you confirm this? Is it a documentation problem or a code problem (or more precisely, should that line be required)?

Curly bracket quantifiers stripped in route check attributes

Using curly bracket quantifiers in check regexp doesn't work. E.g. qr/\d{1,3}/ becomes something like qr/\d1,3/.

I think the offending line is

$pattern =~ s/[{}]//g;

in Kelp::Routes::Pattern line 54

kelp test suite using swat-kelp plugin

Hi Stefan!

I have just created a small test suite for some sanity checks for Kelp framework. Currently is just a proof of concept, but new tests case could be added easily.

This is link for it - https://sparrowhub.org/info/swat-kelp?v=0.000005

Sparrow - you may read about it here - http://blogs.perl.org/users/melezhik/2015/12/sparrowhub---swat-plugins-repository.html or here https://github.com/melezhik/sparrow

What does this test suite check?

• it runs a simple kelp based application ( using plackup and nohup )
• and make a couple of requests ( using curl ) and then analyze the response
• a placeholders routes feature and and Kelp footprint at http header are checked

How does this may help you?

By "you" I mean any Kelp developers , at least you are the one ! (-;

Swat-kelp plugin could be considered as smoke/sanity checks suite or even as regression test suite ( functional testing ) for Kelp framework.

Someone could easily create a test code base for Kelp framework and distribute it over SparrowHub repository, so other developers always may have an actual tests by hand.

Sparrow plugins are versioned and easily to install. Sparrow as well provides some infrastructure to manage and run such a tests ( tests groups, test input parameters ).

Also as swat engine which tests get run by based on real client ( curl ) / server ( run some where ) approach and does not provide any mocks for http requests. These type of testing is more realistic then for example Plack::Test + MockHTTP approach.
From other hand the overhead to create new swat tests is very low - please follow documentation and how simple it could be!

So, let me know what do you think?

Yeah, this is not an issue, it's collaboration request. Don't hesitate to ask me if have any questions.

Thanks.

Alexey

Failed bridge response code

As documentation says 401 Unauthorized response used to tell that it lacks of valid authentication and MUST provide WWW-Authenticate header. This problem solved better by Plack::Middleware::Auth::* module family. But when there is lack of valid rights to access data client should get 403 Forbidden response instead. Thats actually what bridge should do. So I changed tests and response.

Docs from here:
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Kelp::Module::JSON::XS breaks with double-encoding patch

The commit from ruz (cea65c5) breaks the Kelp::Module::JSON::XS-Module as JSON::XS does not have a "property"-function.

The response throws a wierd exception.

Checking for valid environment modes

I see that by design Kelp silently ignores missing mode files (or mode files that exist but are unreadable).

What do you think about adding some type of mode checking?

My initial thought was to require the mode file to be present, even if it's empty. The existence of the files declares the allowed modes.

If that's too stringent, maybe there's another way to declare what modes we want to allow and croak if an invalid mode is supplied?

question about template usage

Hi, this is a question (probably it helps to improve the documentation): how can I setup a layout template so all my other templates inhereits the layout definition?.

Path::Tiny default export 'path' breaks templating

This can be reproduced simply by adding use Path::Tiny to a package that also renders templates. My current "solution" is adding qw() to my use statement, but I don't think this is ideal, as I can't predict which modules would cause similar breakages ahead of time

Template system

The installation on Perl 5.18.0 fails because of Template module. I suggest to change the template system of Kelp, or make it pluggable

JSON and JSON::MaybeXS

Firstly, I think it's about time to remove Kelp::Module::JSON::XS from CPAN. It has been deprecated for almost seven years now and backPAN will hold it forever in case someone still needs it for some reason. No need to create confusion with a module ::XS in search results while the regular JSON module is capable enough. Could you schedule it for deletion please?

Secondly, I suggest changing the JSON manager used by Kelp::Module::JSON from JSON to JSON::MaybeXS. I'm not sure how this should be done - it won't be a breaking change unless someone did something fishy with JSON.pm module-specific methods: backend is_xs is_pp property boolean. I'd see it as an immediate change with no deprecations, as most use cases of JSON are simple encoding and decoding. Can also be a configuration flag for some time (json_maybexs?), off by default, and then on after half a year or other deprecation window.

I've lately changed backend of JSON.pm to Cpanel::JSON::XS with an ENV variable, so that should make both modules equal in effect. The problem is that we can only wish it will be Cpanel::JSON::XS, because if there's any other module somewhere with use JSON; line, it will completely ignore the setting I've put at the top of the Kelp::Module::JSON file. JSON will then still default to JSON::XS, decided at first compile time.

I think the change is worth it for all the improvements of the Cpanel implementation, listed here. I've already tried it locally and all the tests passed except for the one that checked for isa type (no surprise here). Let me know what you think.

Controller Exception Handling

Hello, I try to use Kelp to write some APIs. I use many libs that throw exceptions even on validation level and I would like to handle all of them in one place. As for naked Plack applications I use Plack::Middleware::Exceptions with my own additions.
But Kelp handles exceptions itself and stringifies them.
I curios if it possible for Kelp to rethrow exptions than some kind of Plack::Middleware::Exceptions will handle them.

attr macro and defaults

Hello,

I didn't use your module but i will want to use it in future.
But before i decided to view source
And i think it's bad idea to use like this:

attr attribute_name => {};
attr attribute_name_2 => [];

And so on

You import attr in Base.pm is method and by this line you add $class->attribute_name method with {} as default;

But {} is one time reserved memory (it can one address for all defaults of attribute_name for one runtime process) so i think all default values on one attribute name will point to same hash/array ref memory area. So each request to web application will pollute one hash/array for example for one attribute name.

How do you think?
I think it's buggy behavior,

Kelp::Test doesn't read config properly

# create an app
$ Kelp myTest

# add a line to conf/config.pl
myTest       => 'here is my Test',

$ cat lib/myTest.pm
package myTest;
use Kelp::Base 'Kelp';

sub build {
    my $self = shift;
    my $r    = $self->routes;
    $r->add( '/home', 'home' );
    $r->add( '/config', sub { $_[0]->config_hash } );
my $msg = $self->config( 'myTest' );
print "===\n$msg\n===\n";
}

sub home {
    my $self = shift;
    $self->template('home');
}

1;

$  plackup app.psgi 
===
here is my Test
===
$ perl -Ilib t/main.t 
Use of uninitialized value $msg in concatenation (.) or string at lib/myTest.pm line 10.
===

===
# GET /home
ok 1 - Response code is 200
ok 2 - Content-Type is 'text/html'
ok 3 - Content matches (?-xism:Hello, world!)
1..3

Feature: Automatic Route/Module-Description

We are very happy kelp-users. We are currently building our internal REST-API with very different and complex routes. We choose kelp, as other Perl-Rest-Frameworks are too "selfish" and bloated for our purposes.

But with extending the routes the documentation is getting more and more difficult. Is there an easy way to see the compiled routes, maybe with some descriptive texts. Or is it possible to gather documentation from used modules/routines?

Use of uninitialized value in sprintf at .../Kelp.pm line 149.

The app is being accessed with nginx.
$req->address is an 'undef' value in Kelp.pm while sprintf has to print it...
It is not critical...

$ plackup -E development -s Starman -l /apps/log/WS.sock -a app.psgi
2013/05/02-15:26:48 Starman::Server (type Net::Server::PreFork) starting! pid(15202)
Binding to UNIX socket file "/apps/log/WS.sock"
Setting gid to "65199 65199 115 65199"
Starman: Accepting connections at http://localhost:/apps/log/WS.sock/

Use of uninitialized value in sprintf at /apps/perl-lib/lib/perl5/Kelp.pm line 149. <<<

• - - [02/May/2013:15:30:10 -0400] "GET /WS/qwerty HTTP/1.0" 200 74 "-" "Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.63 Safari/537.31"