NAME

Amon2::Plugin::Web::CpanelJSON - Cpanel::JSON::XS plugin

SYNOPSIS

use Amon2::Lite;
use Cpanel::JSON::XS::Type;
use HTTP::Status qw(:constants);

__PACKAGE__->load_plugins(qw/Web::CpanelJSON/);

use constant HelloWorld => {
    message => JSON_TYPE_STRING,
};

get '/' => sub {
    my $c = shift;
    return $c->render_json(+{ message => 'HELLO!' }, HelloWorld, HTTP_OK);
};

__PACKAGE__->to_app();

DESCRIPTION

This is a JSON plugin for Amon2. The differences from Amon2::Plugin::Web::JSON are as follows.

* Cpanel::JSON::XS::Type is available

* HTTP status code can be specified

* Flexible Configurations

METHODS

• $c->render_json($data, $json_spec, $status=200);

  Generate JSON $data and $json_spec and returns instance of Plack::Response. $json_spec is a structure for JSON encoding defined in Cpanel::JSON::XS::Type.

CONFIGURATION

• json

  Parameters of Cpanel::JSON::XS. Default is as follows:

  ascii => !!1,
  

  Any parameters can be set:

   __PACKAGE__->load_plugins(
      'Web::CpanelJSON' => {
          json => {
              ascii     => 0,
              utf8      => 1,
              canonical => 1,
          }
      }
  );
  

• secure_headers

  Parameters of HTTP::SecureHeaders. Default is as follows:

  content_security_policy           => "default-src 'none'",
  strict_transport_security         => 'max-age=631138519',
  x_content_type_options            => 'nosniff',
  x_download_options                => undef,
  x_frame_options                   => 'DENY',
  x_permitted_cross_domain_policies => 'none',
  x_xss_protection                  => '1; mode=block',
  referrer_policy                   => 'no-referrer',
  

• json_escape_filter

  Escapes JSON to prevent XSS. Default is as follows:

  '+' => '\\u002b',
  '<' => '\\u003c',
  '>' => '\\u003e',
  

• name

  Name of method. Default: 'render_json'

• unbless_object

  Default: undef

  This option is preprocessing coderef encoding an blessed object in JSON. For example, the code using Object::UnblessWithJSONSpec is as follows:

  use Object::UnblessWithJSONSpec ();
  
  __PACKAGE__->load_plugins(
      'Web::CpanelJSON' => {
          unbless_object => \&Object::UnblessWithJSONSpec::unbless_with_json_spec,
      }
  );
  
  ...
  
  package Some::Object {
      use Mouse;
  
      has message => (
          is => 'ro',
      );
  }
  
  my $object = Some::Object->new(message => 'HELLO');
  $c->render_json($object, { message => JSON_TYPE_STRING })
  # => {"message":"HELLO"}
  

• status_code_field

  Default: undef

  It specify the field name of JSON to be embedded in the X-API-Status header. Default is undef. If you set the undef to disable this X-API-Status header.

  __PACKAGE__->load_plugins(
      'Web::CpanelJSON' => { status_code_field => 'status' }
  );
  
  ...
  
  $c->render_json({ status => 200, message => 'ok' })
  # send response header 'X-API-Status: 200'
  

  In general JSON API error code embed in a JSON by JSON API Response body. But can not be logging the error code of JSON for the access log of a general Web Servers. You can possible by using the X-API-Status header.

• defence_json_hijacking_for_legacy_browser

  Default: false

LICENSE

Copyright (C) kfly8.

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

AUTHOR

kfly8 kfly@cpan.org