lib/PublicInbox/URIimap.pm

   1 # Copyright (C) 2020-2021 all contributors <meta@public-inbox.org>
   2 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
   3 # cf. RFC 5092, which the `URI' package doesn't support
   4 #
   5 # This depends only on the documented public API of the `URI' dist,
   6 # not on internal `_'-prefixed subclasses such as `URI::_server'
   7 #
   8 # <https://metacpan.org/pod/URI::imap> exists, but it appears
   9 # unmaintained, isn't in common distros, nor does it support
  10 # ';FOO=BAR' parameters such as UIDVALIDITY
  11 #
  12 # RFC 2192 also describes ";TYPE=<list_type>"
  13 package PublicInbox::URIimap;
  14 use strict;
  15 use v5.10.1;
  16 use URI::Split qw(uri_split uri_join); # part of URI
  17 use URI::Escape qw(uri_unescape uri_escape);
  18 use overload '""' => \&as_string;
  19
  20 my %default_ports = (imap => 143, imaps => 993);
  21 # for enc-auth-type and enc-user in RFC 5092
  22 my $achar = qr/[A-Za-z0-9%\-_\.\!\$'\(\)\+\,\&\=\*]+/;
  23
  24 sub new {
  25         my ($class, $url) = @_;
  26         $url =~ m!\Aimaps?://! ? bless \$url, $class : undef;
  27 }
  28
  29 sub canonical {
  30         my ($self) = @_;
  31
  32         # no #frag in RFC 5092 from what I can tell
  33         my ($scheme, $auth, $path, $query, $_frag) = uri_split($$self);
  34         $path =~ s!\A/+!/!; # excessive leading slash
  35
  36         # upper-case uidvalidity= and uid= parameter names
  37         $path =~ s/;([^=]+)=([^;]*)/;\U$1\E=$2/g;
  38
  39         # lowercase the host portion
  40         $auth =~ s#\A(.*@)?(.*?)(?::([0-9]+))?\z#
  41                 my $ret = ($1//'').lc($2);
  42                 if (defined(my $port = $3)) {
  43                         if ($default_ports{lc($scheme)} != $port) {
  44                                 $ret .= ":$port";
  45                         }
  46                 }
  47                 $ret#ei;
  48
  49         ref($self)->new(uri_join(lc($scheme), $auth, $path, $query));
  50 }
  51
  52 sub host {
  53         my ($self) = @_;
  54         my (undef, $auth) = uri_split($$self);
  55         $auth =~ s!\A.*?@!!;
  56         $auth =~ s!:[0-9]+\z!!;
  57         $auth =~ s!\A\[(.*)\]\z!$1!; # IPv6
  58         uri_unescape($auth);
  59 }
  60
  61 # unescaped, may be used for globbing
  62 sub path {
  63         my ($self) = @_;
  64         my (undef, undef, $path) = uri_split($$self);
  65         $path =~ s!\A/+!!;
  66         $path =~ s!/?;.*\z!!; # [;UIDVALIDITY=nz-number]/;UID=nz-number
  67         $path eq '' ? undef : $path;
  68 }
  69
  70 sub mailbox {
  71         my ($self) = @_;
  72         my $path = path($self);
  73         defined($path) ? uri_unescape($path) : undef;
  74 }
  75
  76 sub uidvalidity { # read/write
  77         my ($self, $val) = @_;
  78         my ($scheme, $auth, $path, $query, $frag) = uri_split($$self);
  79         if (defined $val) {
  80                 if ($path =~ s!;UIDVALIDITY=[^;/]*\b!;UIDVALIDITY=$val!i or
  81                                 $path =~ s!/;!;UIDVALIDITY=$val/;!i) {
  82                         # s// already changed it
  83                 } else { # both s// failed, so just append
  84                         $path .= ";UIDVALIDITY=$val";
  85                 }
  86                 $$self = uri_join($scheme, $auth, $path, $query, $frag);
  87         }
  88         $path =~ s!\A/+!!;
  89         $path =~ m!\A[^;]+;UIDVALIDITY=([1-9][0-9]*)\b!i ?
  90                 ($1 + 0) : undef;
  91 }
  92
  93 sub uid {
  94         my ($self, $val) = @_;
  95         my ($scheme, $auth, $path, $query, $frag) = uri_split($$self);
  96         if (scalar(@_) == 2) {
  97                 if (!defined $val) {
  98                         $path =~ s!/;UID=[^;/]*\b!!i;
  99                 } else {
 100                         $path =~ s!/;UID=[^;/]*\b!/;UID=$val!i or
 101                                 $path .= "/;UID=$val";
 102                 }
 103                 $$self = uri_join($scheme, $auth, $path, $query);
 104         }
 105         $path =~ m!\A/[^;]+(?:;UIDVALIDITY=[^;/]+)?/;UID=([1-9][0-9]*)\b!i ?
 106                 ($1 + 0) : undef;
 107 }
 108
 109 sub port {
 110         my ($self) = @_;
 111         my ($scheme, $auth) = uri_split($$self);
 112         $auth =~ /:([0-9]+)\z/ ? $1 + 0 : $default_ports{lc($scheme)};
 113 }
 114
 115 sub authority {
 116         my ($self) = @_;
 117         my (undef, $auth) = uri_split($$self);
 118         $auth
 119 }
 120
 121 sub user {
 122         my ($self, $val) = @_;
 123         my ($scheme, $auth, $path, $query) = uri_split($$self);
 124         my $at_host_port;
 125         $auth =~ s/(@.*)\z// and $at_host_port = $1; # stash host:port for now
 126         if (scalar(@_) == 2) { # set, this clobbers password, too
 127                 if (defined $val) {
 128                         my $uval = uri_escape($val);
 129                         if (defined($at_host_port)) {
 130                                 $auth =~ s!\A.*?(;AUTH=$achar).*!$uval$1!ix
 131                                         or $auth = $uval;
 132                         } else {
 133                                 substr($auth, 0, 0) = "$uval@";
 134                         }
 135                 } elsif (defined($at_host_port)) { # clobber
 136                         $auth =~ s!\A.*?(;AUTH=$achar).*!$1!i or $auth = '';
 137                         if ($at_host_port && $auth eq '') {
 138                                 $at_host_port =~ s/\A\@//;
 139                         }
 140                 }
 141                 $at_host_port //= '';
 142                 $$self = uri_join($scheme, $auth.$at_host_port, $path, $query);
 143                 $val;
 144         } else { # read-only
 145                 $at_host_port // return undef; # explicit undef for scalar
 146                 $auth =~ s/;.*\z//; # drop ;AUTH=...
 147                 $auth =~ s/:.*\z//; # drop password
 148                 $auth eq '' ? undef : uri_unescape($auth);
 149         }
 150 }
 151
 152 sub password {
 153         my ($self) = @_;
 154         my (undef, $auth) = uri_split($$self);
 155         $auth =~ s/@.*\z// or return undef; # drop host:port
 156         $auth =~ s/;.*\z//; # drop ;AUTH=...
 157         $auth =~ s/\A[^:]+:// ? uri_unescape($auth) : undef; # drop ->user
 158 }
 159
 160 sub auth {
 161         my ($self, $val) = @_;
 162         my ($scheme, $auth, $path, $query) = uri_split($$self);
 163         my $at_host_port;
 164         $auth =~ s/(@.*)\z// and $at_host_port = $1; # stash host:port for now
 165         if (scalar(@_) == 2) {
 166                 if (defined $val) {
 167                         my $uval = uri_escape($val);
 168                         if ($auth =~ s!;AUTH=$achar!;AUTH=$uval!ix) {
 169                                 # replaced existing
 170                         } elsif (defined($at_host_port)) {
 171                                 $auth .= ";AUTH=$uval";
 172                         } else {
 173                                 substr($auth, 0, 0) = ";AUTH=$uval@";
 174                         }
 175                 } else { # clobber
 176                         $auth =~ s!;AUTH=$achar!!i;
 177                         if ($at_host_port && $auth eq '') {
 178                                 $at_host_port =~ s/\A\@//;
 179                         }
 180                 }
 181                 $at_host_port //= '';
 182                 $$self = uri_join($scheme, $auth.$at_host_port, $path, $query);
 183                 $val;
 184         } else { # read-only
 185                 $auth =~ /;AUTH=(.+)\z/i ? uri_unescape($1) : undef;
 186         }
 187 }
 188
 189 sub scheme {
 190         my ($self) = @_;
 191         (uri_split($$self))[0];
 192 }
 193
 194 sub as_string { ${$_[0]} }
 195
 196 sub clone { ref($_[0])->new(as_string($_[0])) }
 197
 198 1;