| 1 | package Web::VWF::Config; | ||
| 2 | |||
| 3 | # VWF is licensed under GPL2.0 for personal use only | ||
| 4 | # njh@bandsman.co.uk | ||
| 5 | |||
| 6 | # Usage is subject to licence terms. | ||
| 7 | # The licence terms of this software are as follows: | ||
| 8 | # Personal single user, single computer use: GPL2 | ||
| 9 | # All other users (including Commercial, Charity, Educational, Government) | ||
| 10 | # must apply in writing for a licence for use from Nigel Horne at the | ||
| 11 | # above e-mail. | ||
| 12 | |||
| 13 | use warnings; | ||
| 14 | use strict; | ||
| 15 | |||
| 16 | use Carp; | ||
| 17 | use Config::Abstraction; | ||
| 18 | use CGI::Info; | ||
| 19 | use Data::Dumper; | ||
| 20 | use Web::VWF::Utils (); | ||
| 21 | use Error::Simple; | ||
| 22 | use File::Spec; | ||
| 23 | use Params::Get 0.13; | ||
| 24 | |||
| 25 | =encoding utf-8 | ||
| 26 | |||
| 27 | =head1 NAME | ||
| 28 | |||
| 29 | Web::VWF::Config - Site-independent configuration file for the Versatile Web Framework | ||
| 30 | |||
| 31 | =head1 VERSION | ||
| 32 | |||
| 33 | Version 0.003.0 | ||
| 34 | |||
| 35 | =cut | ||
| 36 | |||
| 37 | use version; our $VERSION = version->declare('0.003.0'); | ||
| 38 | |||
| 39 | # Where the server keeps one configuration directory per site, named after the | ||
| 40 | # site - see Web::VWF::directory() | ||
| 41 | our $DEFAULT_DIRECTORY = '/usr/lib/vwf'; | ||
| 42 | |||
| 43 | =head1 SUBROUTINES/METHODS | ||
| 44 | |||
| 45 | =head2 new | ||
| 46 | |||
| 47 | Creates a new Web::VWF::Config instance with hierarchical configuration loading. | ||
| 48 | |||
| 49 | Takes four optional arguments: | ||
| 50 | info (CGI::Info object) | ||
| 51 | logger | ||
| 52 | config_directory - used when the configuration directory can't be worked out | ||
| 53 | config_file - name of the configuration file - otherwise determined dynamically | ||
| 54 | config (ref to hash of values to override in the config file | ||
| 55 | |||
| 56 | Values in the file are overridden by what's in the environment | ||
| 57 | |||
| 58 | B<Parameters:> | ||
| 59 | |||
| 60 | =over 4 | ||
| 61 | |||
| 62 | =item * C<info> - CGI::Info object (optional, created if not provided) | ||
| 63 | |||
| 64 | =item * C<logger> - Logger object with debug() method (optional) | ||
| 65 | |||
| 66 | =item * C<config_directory> - Additional config directory path (optional) | ||
| 67 | |||
| 68 | =item * C<config_file> - Specific config filename (optional) | ||
| 69 | |||
| 70 | =item * C<config> - Hash ref of override values (optional) | ||
| 71 | |||
| 72 | =back | ||
| 73 | |||
| 74 | B<Configuration Resolution Order:> | ||
| 75 | 1. Base configuration files | ||
| 76 | 2. Values from config parameter | ||
| 77 | 3. Environment variable overrides | ||
| 78 | |||
| 79 | B<Directory Search Order:> | ||
| 80 | 1. $ENV{CONFIG_DIR} (if set) | ||
| 81 | 2. Provided config_directory | ||
| 82 | 3. ../conf relative to script | ||
| 83 | 4. ../../conf relative to script | ||
| 84 | 5. $DOCUMENT_ROOT/../lib/conf | ||
| 85 | 6. $HOME/lib/conf | ||
| 86 | |||
| 87 | B<Returns:> Blessed Web::VWF::Config object | ||
| 88 | |||
| 89 | B<Throws:> Error::Simple on configuration errors | ||
| 90 | |||
| 91 | =head3 FORMAL SPECIFICATION | ||
| 92 | |||
| 93 | [STRING, HASH, LOGGER] | ||
| 94 | |||
| 95 | ConfigState ::= ⟨⟨ config_dirs : ℙ STRING; | ||
| 96 | config_data : HASH; | ||
| 97 | logger : LOGGER ⟩⟩ | ||
| 98 | |||
| 99 | ConfigArgs ::= ⟨⟨ info : CGI_Info; | ||
| 100 | logger : LOGGER; | ||
| 101 | config_directory : STRING; | ||
| 102 | config_file : STRING; | ||
| 103 | config : HASH ⟩⟩ | ||
| 104 | |||
| 105 | Init : ConfigArgs → ConfigState | ||
| 106 | |||
| 107 | ∀ params : ConfigArgs • | ||
| 108 | let dirs == if env.CONFIG_DIR ≠ ∅ | ||
| 109 | then {env.CONFIG_DIR} | ||
| 110 | else default_dirs ∪ {params.config_directory} fi • | ||
| 111 | let valid_dirs == {d : dirs | ∃ f : FILE • readable(d, f)} • | ||
| 112 | valid_dirs ≠ ∅ ∧ | ||
| 113 | config_data ∈ HASH ∧ | ||
| 114 | config_data = merge(file_config, params.config, env_overrides) | ||
| 115 | |||
| 116 | ValidConfigKey == {k : STRING | k ∈ dom config_data} | ||
| 117 | |||
| 118 | GetConfigValue : ValidConfigKey → (STRING ∪ HASH ∪ ARRAY) | ||
| 119 | |||
| 120 | =cut | ||
| 121 | |||
| 122 | sub new | ||
| 123 | { | ||
| 124 | my $proto = shift; | ||
| 125 | my $params = Params::Get::get_params(undef, @_); | ||
| 126 | |||
| 127 | if (exists $params->{logger} && defined $params->{logger}) { | ||
| 128 | throw Error::Simple('logger must be an object with debug method') | ||
| 129 | unless ref($params->{logger}) && $params->{logger}->can('debug'); | ||
| 130 | } | ||
| 131 | |||
| 132 | if($params->{'logger'}) { | ||
| 133 | $params->{'logger'}->debug(__PACKAGE__, '->new()'); | ||
| 134 | } | ||
| 135 | |||
| 136 | if(exists $params->{config} && defined $params->{config}) { | ||
| 137 | throw Error::Simple('config must be a hash reference') unless ref($params->{config}) eq 'HASH'; | ||
| 138 | } | ||
| 139 | |||
| 140 | my $class = ref($proto) || $proto; | ||
| 141 | my $info = $params->{info} || CGI::Info->new(); | ||
| 142 | |||
| 143 | my @config_dirs; | ||
| 144 | if($ENV{'CONFIG_DIR'}) { | ||
| 145 | # Validate directory exists | ||
| 146 | throw Error::Simple("CONFIG_DIR '$ENV{CONFIG_DIR}' does not exist or is not readable") | ||
| 147 | unless -d $ENV{'CONFIG_DIR'} && -r $ENV{'CONFIG_DIR'}; | ||
| 148 | @config_dirs = ($ENV{'CONFIG_DIR'}); | ||
| 149 | } else { | ||
| 150 | # Build the standard search path; caller's config_directory is prepended below | ||
| 151 | @config_dirs = ( | ||
| 152 | File::Spec->catdir( | ||
| 153 | $info->script_dir(), | ||
| 154 | File::Spec->updir(), | ||
| 155 | File::Spec->updir(), | ||
| 156 | 'conf' | ||
| 157 | ), File::Spec->catdir( | ||
| 158 | $info->script_dir(), | ||
| 159 | File::Spec->updir(), | ||
| 160 | 'conf' | ||
| 161 | ) | ||
| 162 | ); | ||
| 163 | |||
| 164 | # The server's own directory for this site, used when the site keeps no | ||
| 165 | # conf/ beside its cgi-bin/. The domain name comes from the Host header, | ||
| 166 | # so it must look like a host name before it is made part of a path | ||
| 167 | if(defined(my $directory = $params->{'directory'})) { | ||
| 168 | throw Error::Simple('directory must be a string') if ref($directory); | ||
| 169 | my $domain = $info->domain_name(); | ||
| 170 | if(defined($domain) && ($domain =~ /\A[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\z/)) { | ||
| 171 | push @config_dirs, File::Spec->catdir($directory, $domain); | ||
| 172 | } | ||
| 173 | } | ||
| 174 | |||
| 175 | if($ENV{'DOCUMENT_ROOT'}) { | ||
| 176 | push(@config_dirs, File::Spec->catdir( | ||
| 177 | $ENV{'DOCUMENT_ROOT'}, | ||
| 178 | File::Spec->updir(), | ||
| 179 | 'lib', | ||
| 180 | 'conf' | ||
| 181 | )) | ||
| 182 | } | ||
| 183 | if($ENV{'HOME'}) { | ||
| 184 | push(@config_dirs, File::Spec->catdir( | ||
| 185 | $ENV{'HOME'}, | ||
| 186 | 'lib', | ||
| 187 | 'conf' | ||
| 188 | )); | ||
| 189 | } | ||
| 190 | |||
| 191 | # Prepend the caller-supplied directory so it takes highest precedence | ||
| 192 | if($params->{config_directory}) { | ||
| 193 | throw Error::Simple("config_directory must be a string") if ref($params->{config_directory}); | ||
| 194 | throw Error::Simple("config_directory '$params->{config_directory}' does not exist") | ||
| 195 | unless -d $params->{config_directory}; | ||
| 196 | unshift @config_dirs, $params->{config_directory}; | ||
| 197 | } | ||
| 198 | } | ||
| 199 | |||
| 200 | # Look for localised configurations | ||
| 201 | my $language; | ||
| 202 | if(my $lingua = $params->{'lingua'}) { | ||
| 203 | $language = $lingua->language_code_alpha2(); | ||
| 204 | } | ||
| 205 | $language ||= $info->lang(); | ||
| 206 | |||
| 207 | if($language) { | ||
| 208 | @config_dirs = map { | ||
| 209 | ($_, "$_/default", "$_/$language") | ||
| 210 | } @config_dirs; | ||
| 211 | } else { | ||
| 212 | @config_dirs = map { | ||
| 213 | ($_, File::Spec->catdir($_, 'default')) | ||
| 214 | } @config_dirs; | ||
| 215 | } | ||
| 216 | |||
| 217 | if($params->{'debug'}) { | ||
| 218 | # Not sure this really does anything | ||
| 219 | # $Config::Auto::Debug = 1; | ||
| 220 | |||
| 221 | if($params->{logger}) { | ||
| 222 | while(my ($key,$value) = each %ENV) { | ||
| 223 | if($value) { | ||
| 224 | $params->{logger}->debug("$key=$value"); | ||
| 225 | } | ||
| 226 | } | ||
| 227 | } | ||
| 228 | } | ||
| 229 | |||
| 230 | my $config; | ||
| 231 | eval { | ||
| 232 | $config = Config::Abstraction->new( | ||
| 233 | config_dirs => \@config_dirs, | ||
| 234 | config_files => ['default', $info->domain_name(), $ENV{'CONFIG_FILE'}, $params->{'config_file'}], | ||
| 235 | logger => $params->{'logger'} | ||
| 236 | )->all(); | ||
| 237 | }; | ||
| 238 | if($@ || !defined($config)) { | ||
| 239 | throw Error::Simple("Configuration error: $@"); | ||
| 240 | } | ||
| 241 | |||
| 242 | # Validate essential configuration structure | ||
| 243 | throw Error::Simple('Configuration must be a hash reference') unless(ref($config) eq 'HASH'); | ||
| 244 | |||
| 245 | # The values in config are defaults which can be overridden by | ||
| 246 | # the values in params->{config} | ||
| 247 | if(defined($params->{'config'})) { | ||
| 248 | $config = { %{$config}, %{$params->{'config'}} }; | ||
| 249 | } | ||
| 250 | |||
| 251 | # Allow variables to be overridden by the environment | ||
| 252 | foreach my $key(keys %{$config}) { | ||
| 253 | if(my $value = $ENV{$key}) { | ||
| 254 | # Validate environment variable names | ||
| 255 | # throw Error::Simple("Invalid environment variable name: $key") | ||
| 256 | # unless $key =~ /^[A-Z_][A-Z0-9_]*$/; | ||
| 257 | |||
| 258 | # Sanitize values | ||
| 259 | # $value =~ s/[^\w\s=\.\-]//g; # Remove potentially dangerous characters | ||
| 260 | |||
| 261 | if($params->{'logger'}) { | ||
| 262 | $params->{'logger'}->debug(__PACKAGE__, ': ', __LINE__, " overwriting $key, ", $config->{$key}, " with $value"); | ||
| 263 | } | ||
| 264 | # If the value contains an equals make it into a hash value | ||
| 265 | if($value =~ /(.+)=(.+)/) { | ||
| 266 | delete $config->{$key} if(!ref($config->{$key})); | ||
| 267 | $config->{$key}{$1} = $2; | ||
| 268 | } else { | ||
| 269 | $config->{$key} = $value; | ||
| 270 | } | ||
| 271 | } | ||
| 272 | } | ||
| 273 | |||
| 274 | # Config::Any turns fields with spaces into arrays, put them back | ||
| 275 | foreach my $field('Contents', 'SiteTitle') { | ||
| 276 | next if(!exists $config->{$field}); | ||
| 277 | my $value = $config->{$field}; | ||
| 278 | |||
| 279 | if(ref($value) eq 'ARRAY') { | ||
| 280 | $config->{$field} = join(' ', @{$value}); | ||
| 281 | } | ||
| 282 | } | ||
| 283 | |||
| 284 | # unless($config->{'config_path'}) { | ||
| 285 | # $config->{'config_path'} = File::Spec->catdir($config_dir, $info->domain_name()); | ||
| 286 | # } | ||
| 287 | if($params->{'debug'} && $params->{'logger'}) { | ||
| 288 | $params->{'logger'}->debug(__PACKAGE__, '(', __LINE__, '): ', Data::Dumper->new([Web::VWF::Utils::redact_config($config)])->Dump()); | ||
| 289 | } | ||
| 290 | |||
| 291 | return bless $config, $class; | ||
| 292 | } | ||
| 293 | |||
| 294 | sub AUTOLOAD | ||
| 295 | { | ||
| 296 | our $AUTOLOAD; | ||
| 297 | my $self = shift; | ||
| 298 | |||
| 299 | # Called as a class method there is no hash to look in | ||
| 300 | return undef unless(ref($self)); | ||
| 301 | return unless defined($AUTOLOAD); | ||
| 302 | |||
| 303 | # Extract the key name from the AUTOLOAD variable | ||
| 304 | (my $key = $AUTOLOAD) =~ s/.*:://; | ||
| 305 | |||
| 306 | return unless defined($key); | ||
| 307 | |||
| 308 | # Don't handle special methods | ||
| 309 | return if $key eq 'DESTROY'; | ||
| 310 | |||
| 311 | # Validate method name - only allow safe config keys | ||
| 312 | Carp::croak(__PACKAGE__, ": Invalid key name: $key") unless $key =~ /^[a-zA-Z_][a-zA-Z0-9_]*$/; | ||
| 313 | |||
| 314 | # Return the value of the corresponding hash key | ||
| 315 | # Only return existing keys to avoid auto-vivification | ||
| 316 | return exists $self->{$key} ? $self->{$key} : undef; | ||
| 317 | } | ||
| 318 | |||
| 319 | 1; | ||
| 320 | |||
| 321 | =head1 AUTHOR | ||
| 322 | |||
| 323 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||
| 324 | |||
| 325 | =head1 LICENCE AND COPYRIGHT | ||
| 326 | |||
| 327 | Copyright 2010-2026 Nigel Horne. | ||
| 328 | |||
| 329 | Usage is subject to the GPL2 licence terms. | ||
| 330 | If you use it, | ||
| 331 | please let me know. | ||
| 332 | |||
| 333 | =cut |