view release on metacpan or  search on metacpan

lib/Developer/Dashboard/Codec.pm  view on Meta::CPAN

package Developer::Dashboard::Codec;

use strict;
use warnings;

our $VERSION = '4.16';

use Exporter 'import';
use IO::Compress::Gzip qw(gzip $GzipError);
use IO::Uncompress::Gunzip qw(gunzip $GunzipError);
use MIME::Base64 qw(encode_base64 decode_base64);

our @EXPORT_OK = qw(encode_payload decode_payload);

# encode_payload($text)
# Compresses and base64-encodes a text payload.
# Input: scalar text value.
# Output: encoded scalar token or undef for undefined/empty input.
sub encode_payload {
    my ($text) = @_;
    return if !defined $text;

    gzip \$text => \my $zipped
      or die "gzip failed: $GzipError";

    return encode_base64( $zipped, '' );
}

# decode_payload($token)
# Decodes and inflates a previously encoded payload token.
# Input: base64 token scalar.
# Output: decoded text scalar or undef for undefined/empty input.
sub decode_payload {
    my ($token) = @_;
    return if !defined $token || $token eq '';

    my $zipped = decode_base64($token);
    gunzip \$zipped => \my $text
      or die "gunzip failed: $GunzipError";

    return $text;
}

1;

__END__

=head1 NAME

Developer::Dashboard::Codec - payload encoding helpers for Developer Dashboard

=head1 SYNOPSIS

  use Developer::Dashboard::Codec qw(encode_payload decode_payload);
  my $token = encode_payload($text);
  my $text  = decode_payload($token);

=head1 DESCRIPTION

This module provides the compact payload transport used by Developer
Dashboard for transient page and action tokens.

=head1 FUNCTIONS

=head2 encode_payload

Compress and base64-encode a text payload.

=head2 decode_payload

Decode and inflate a token back to text.

=for comment FULL-POD-DOC START

=head1 PURPOSE

This module implements the compressed token format used by transient page URLs and action payloads. It gzips text payloads and base64-encodes them for transport, then reverses that process when a token comes back into the runtime.

=head1 WHY IT EXISTS

It exists because token encoding is a core transport contract shared by bookmarks, Ajax helpers, and page/action flows. Keeping that codec in one place prevents subtle mismatches between producers and consumers.

=head1 WHEN TO USE

Use this file when changing token size, encoding behavior, compression handling, or any flow that creates or reads the portable payload tokens used in URLs and form posts.

=head1 HOW TO USE

Import C<encode_payload> and C<decode_payload> where a runtime component needs to turn text into a transport token or recover the original text from one. The interface is intentionally small so the token contract stays easy to reason about.

=head1 WHAT USES IT