package Apache::Inject;

use 5.008000;
use strict;
use warnings;

our $VERSION = '0.01';

use Apache2::CmdParms ();
use Apache2::Module ();
use Apache2::Const qw/OR_LIMIT OR_AUTHCFG TAKE12/;

my @directives = (
	{ name => 'Inject',
	  func => __PACKAGE__.'::Inject',
	  req_override => OR_LIMIT|OR_AUTHCFG,
	  args_how => TAKE12,
	  errmsg => 'Inject HeadFile[!] FootFile[!]' }
);
Apache2::Module::add(__PACKAGE__, \@directives);

sub Inject {
	my ($self, $parms, @args) = @_;

	# Construct directives for passing arguments to handler
	my @vars;
	my @names = qw/InjectHead InjectFoot/;
	for (@args) {
		s/\\/\\\\/; s/"/\\"/;
		push @vars, 'PerlSetVar ' . (shift @names) . ' "' . $_ . '"';
	}

	# Add relevant directives to current configuration
	$parms->add_config(['SetHandler perl-script',
	                    'PerlResponseHandler Apache::Inject::Handler',
	                    @vars]);
}

1;
__END__
=encoding latin1

=head1 NAME

Apache::Inject - Apache directive for injecting HTML headers and footers

=head1 SYNOPSIS

  DocumentRoot /uar/local/www/apache24/data
  PerlLoadModule Apache::Inject
  <Directory /usr/local/www/apache24/data>
      Inject head.html foot.html
  </Directory>

=head1 DESCRIPTION

Apache::Inject is a mod_perl module that adds an Apache directive
called Inject.

The Inject directive takes one or two arguments, which correspond
to the file names of two HTML files in the document root.  The
contents of these files are then inserted into any requested HTML
file.  The first file (the header) is inserted before the body of
the requested HTML file, while the second file (the footer) is
inserted after the body.

The directive is smart enough to place the header and footer in the
proper places.  The contents of the header file is inserted after
any elements belonging to E<lt>headE<gt> and before any elements
belonging to E<lt>bodyE<gt> (regardless of whether any explicit
E<lt>headE<gt> or E<lt>bodyE<gt> tag is present in the source of
the requested HTML page).  Likewise, the contents of the second
file is placed before any potential final E<lt>/htmlE<gt>.

Please note:

=over

=item *
The Inject directive is valid only inside directory sections, such
as E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesMatchE<gt>
blocks.  It is valid in .htaccess files if AllowOverride
Limit/AuthConfig/All is enabled.

=item *
The file paths given to Inject are relative to the document root
of the current server or virtual server.

=item *
Apache::Inject is designed for injecting headers and footers that
belong in the E<lt>bodyE<gt> element, such as headings, menu bars
and copyright notices.  It is not built for inserting E<lt>headE<gt>
elements.

=back

=head1 INSTALLATION

To install this module type the following:

  perl Makefile.PL
  make
  make test
  make install

=head1 OPERATION

Behind the scenes, the Inject directive works as an alias for
PerlResponseHandler and PerlSetVar.  For example, C<Inject head.html
foot.html> results in the following configuration being added:

  PerlResponseHandler Apache::Inject::Handler
  PerlSetVar InjectHeader head.html
  PerlSetVar InjectFooter foot.html

This results in Apache::Inject::Handler being registered as a handler
for requests to the current directory or location.

Apache::Inject::Handler accepts all requests to files where the
content type is C<text/html>.  It reads the contents of the requested
file, as well as the contents of the C<InjectHeader> and C<InjectFooter>
files, concatenates them intelligently and prints their combined
contents.

=head1 DIAGNOSTICS

Apache::Inject::Handler logs all errors and warnings to the Apache
log file.  Below is a list of all issued errors and warnings.

Note that whenever Apache::Inject::Handler issues an error or a
warning, this means that it also declines the request, letting
Apache handle it as it would if the Inject directive were not used.

=over

=item Error: InjectHead/InjectFoot should not begin with slash, as
it is already always relative to document root

The paths given to Inject are always relative to the document root,
even if the Inject directive is located within a directory section
that applies to another path.

Beginning any of the paths with a slash implies that there would
be some difference in behavior compared to omitting the slash, which
is false.

=item Error: InjectHead/InjectFoot cannot extend past document root

This error is issued if any of the paths given to Inject tries to
go above the document root by using C<../>.

=item Error: InjectHead/InjectFoot I<path/to/file> does not exist

This error is issued if any of the paths given to Inject doesn't
exist.

=item Warning: Declining request due to empty document root

This warning is issued if Apache::Inject::Handler for some reason
cannot retrieve the current document root from Apache.

=back

=head1 CAVEATS

On FreeBSD, you need to enable the accf_http kernel module in order
for the tests to work.  Note that Apache::Inject works fine without
the module; it is only the tests that require it.

=head1 AUTHOR

John Ankarström, E<lt>john [at] ankarstrom.seE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2021 by John Ankarström

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

=cut