[PATCH 0/3] init: add manpage and locking

[PATCH 0/3] init: add manpage and locking

[Eric Wong]

And this reminds me, --skip-articles needs to be added for
--skip-epoch to make sense, too..

Eric Wong (3):
  init: favor --skip-epoch instead of --skip
  doc: add manpage for public-inbox-init(1)
  init: implement locking

 Documentation/include.mk            |  1 +
 Documentation/public-inbox-init.pod | 86 +++++++++++++++++++++++++++++
 MANIFEST                            |  1 +
 script/public-inbox-init            | 39 ++++++++++---
 t/init.t                            | 18 +++++-
 5 files changed, 135 insertions(+), 10 deletions(-)
 create mode 100644 Documentation/public-inbox-init.pod

-- 
EW

[PATCH 1/3] init: favor --skip-epoch instead of --skip

[Eric Wong]

Since I intend to add support for --skip-artnum, disambiguating
the long option name makes sense.  We'll support --skip
indefinitely for compatibility.
---
 script/public-inbox-init | 15 ++++++++-------
 t/init.t                 |  6 +++---
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/script/public-inbox-init b/script/public-inbox-init
index 98aea4bf..39f2a067 100755
--- a/script/public-inbox-init
+++ b/script/public-inbox-init
@@ -20,10 +20,11 @@ sub x { system(@_) and die join(' ', @_). " failed: $?\n" }
 sub usage { print STDERR "Usage: $usage\n"; exit 1 }
 my $version = undef;
 my $indexlevel = undef;
-my $skip;
-my %opts = ( 'V|version=i' => \$version,
-	     'L|indexlevel=s' => \$indexlevel,
-	     'S|skip=i' => \$skip,
+my $skip_epoch;
+my %opts = (
+	'V|version=i' => \$version,
+	'L|indexlevel=s' => \$indexlevel,
+	'S|skip|skip-epoch=i' => \$skip_epoch,
 );
 GetOptions(%opts) or usage();
 PublicInbox::Admin::indexlevel_ok_or_die($indexlevel) if defined $indexlevel;
@@ -104,8 +105,8 @@ if (-f "$mainrepo/inbox.lock") {
 
 $version = 1 unless defined $version;
 
-if ($version == 1 && defined $skip) {
-	die "--skip is only supported for -V2 repos\n";
+if ($version == 1 && defined $skip_epoch) {
+	die "--skip-epoch is only supported for -V2 repos\n";
 }
 
 my $ibx = PublicInbox::Inbox->new({
@@ -117,7 +118,7 @@ my $ibx = PublicInbox::Inbox->new({
 });
 
 my $creat_opt = {};
-PublicInbox::InboxWritable->new($ibx, $creat_opt)->init_inbox(0, $skip);
+PublicInbox::InboxWritable->new($ibx, $creat_opt)->init_inbox(0, $skip_epoch);
 
 # needed for git prior to v2.1.0
 umask(0077) if defined $perm;
diff --git a/t/init.t b/t/init.t
index e2dd306d..667b09fe 100644
--- a/t/init.t
+++ b/t/init.t
@@ -86,15 +86,15 @@ SKIP: {
 	for (1..2) {
 		@cmd = (pi_init, '-V2', '-S1', 'skip1', "$tmpdir/skip1",
 			   qw(http://example.com/skip1 skip1@example.com));
-		is(system(@cmd), 0, "--skip 1");
+		is(system(@cmd), 0, "--skip-epoch 1");
 		my $gits = [ glob("$tmpdir/skip1/git/*.git") ];
 		is_deeply($gits, ["$tmpdir/skip1/git/1.git"], 'skip OK');
 	}
 
 
-	@cmd = (pi_init, '-V2', '--skip=2', 'skip2', "$tmpdir/skip2",
+	@cmd = (pi_init, '-V2', '--skip-epoch=2', 'skip2', "$tmpdir/skip2",
 		   qw(http://example.com/skip2 skip2@example.com));
-	is(system(@cmd), 0, "--skip 2");
+	is(system(@cmd), 0, "--skip-epoch 2");
 	my $gits = [ glob("$tmpdir/skip2/git/*.git") ];
 	is_deeply($gits, ["$tmpdir/skip2/git/2.git"], 'skipping 2 works, too');
 }
-- 
EW

[PATCH 2/3] doc: add manpage for public-inbox-init(1)

[Eric Wong]

This old command was lacking a manpage, so (finally) create one.
---
 Documentation/include.mk            |  1 +
 Documentation/public-inbox-init.pod | 86 +++++++++++++++++++++++++++++
 MANIFEST                            |  1 +
 3 files changed, 88 insertions(+)
 create mode 100644 Documentation/public-inbox-init.pod

diff --git a/Documentation/include.mk b/Documentation/include.mk
index 9a132962..55c10b51 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -36,6 +36,7 @@ m1 += public-inbox-convert
 m1 += public-inbox-edit
 m1 += public-inbox-httpd
 m1 += public-inbox-index
+m1 += public-inbox-init
 m1 += public-inbox-mda
 m1 += public-inbox-nntpd
 m1 += public-inbox-watch
diff --git a/Documentation/public-inbox-init.pod b/Documentation/public-inbox-init.pod
new file mode 100644
index 00000000..377fb2a2
--- /dev/null
+++ b/Documentation/public-inbox-init.pod
@@ -0,0 +1,86 @@
+=head1 NAME
+
+public-inbox-init - create or reinitialize a public-inbox
+
+=head1 SYNOPSIS
+
+B<public-inbox-init> [OPTIONS] NAME INBOX_DIR HTTP_URL ADDRESS [ADDRESS..]
+
+=head1 DESCRIPTION
+
+Creates an empty public-inbox or reinitializes an existing one.
+It updates C<~/.public-inbox/config> by creating a
+C<[publicinbox "NAME"]> section where
+C<publicinbox.NAME.mainrepo> is C<INBOX_DIR>,
+C<publicinbox.NAME.url> is C<HTTP_URL>, and
+C<publicinbox.NAME.address> is C<ADDRESS>.  Multiple addresses
+may be specified for inboxes with multiple addresses.
+
+=head1 OPTIONS
+
+=over
+
+=item -V, --version FORMAT_VERSION
+
+Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
+if you have L<DBD::SQLite> installed.
+
+The default is C<1> for the old L<public-inbox-v1-format(5)>,
+but C<2> is strongly recommended for scalability if you have
+L<DBD::SQLite>.
+
+Default: C<1>
+
+=item --indexlevel <basic|medium|full>
+
+Controls the indexing level for L<public-inbox-index(1)>
+
+See L<public-inbox-config(5)> for more information.
+
+Default: C<full>
+
+=item -S, --skip-epoch
+
+For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
+allows archivists to publish incomplete archives with newer
+mail while allowing "0.git" (or "1.git" and so on) epochs to be
+added-after-the-fact (without affecting "git clone" followers).
+
+Default: unset, no epochs are skipped
+
+=back
+
+=head1 ENVIRONMENT
+
+=over 8
+
+=item PI_CONFIG
+
+Used to override the default C<~/.public-inbox/config> value.
+
+=back
+
+=head1 LIMITATIONS
+
+This tool predates NNTP support in public-inbox and is missing
+C<newsgroup> and many of the options documented in
+L<public-inbox-config(5)>.  See L<public-inbox-config(5)> for all the
+options which may be applied to a given inbox.
+
+=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
+
+The mail archives are hosted at L<https://public-inbox.org/meta/>
+and L<http://hjrcffqmbrq6wope.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright 2019 all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<git-init(1)>, L<git-config(1)>, L<public-inbox-v1-format(5)>,
+L<public-inbox-v2-format(5)>
diff --git a/MANIFEST b/MANIFEST
index ecf239f4..b3046cf6 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -20,6 +20,7 @@ Documentation/public-inbox-daemon.pod
 Documentation/public-inbox-edit.pod
 Documentation/public-inbox-httpd.pod
 Documentation/public-inbox-index.pod
+Documentation/public-inbox-init.pod
 Documentation/public-inbox-mda.pod
 Documentation/public-inbox-nntpd.pod
 Documentation/public-inbox-overview.pod
-- 
EW

[PATCH 3/3] init: implement locking

[Eric Wong]

First, we use flock(2) to wait on parallel public-inbox-init(1)
invocations while we make multiple changes using git-config(1).
This flock allows -init processes to wait on each other if using
reasonable POSIX filesystems.

Then, we also need a git-config(1)-compatible lock to prevent
user-invoked git-config(1) processes from clobbering our
changes while we're holding the flock.
---
 script/public-inbox-init | 24 ++++++++++++++++++++++++
 t/init.t                 | 12 ++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/script/public-inbox-init b/script/public-inbox-init
index 39f2a067..8fd2f9dc 100755
--- a/script/public-inbox-init
+++ b/script/public-inbox-init
@@ -12,8 +12,10 @@ PublicInbox::Admin::require_or_die('-base');
 require PublicInbox::Config;
 require PublicInbox::InboxWritable;
 use File::Temp qw/tempfile/;
+use PublicInbox::Lock;
 use File::Basename qw/dirname/;
 use File::Path qw/mkpath/;
+use Fcntl qw(:DEFAULT);
 use Cwd qw/abs_path/;
 
 sub x { system(@_) and die join(' ', @_). " failed: $?\n" }
@@ -38,7 +40,29 @@ my %seen;
 my $pi_config = PublicInbox::Config->default_file;
 my $dir = dirname($pi_config);
 mkpath($dir); # will croak on fatal errors
+
+# first, we grab a flock to prevent simultaneous public-inbox-init
+# processes from trampling over each other, or exiting with 255 on
+# O_EXCL failure below.  This gets unlocked automatically on exit:
+my $lock_obj = { lock_path => "$pi_config.flock" };
+PublicInbox::Lock::lock_acquire($lock_obj);
+
+# git-config will operate on this (and rename on success):
 my ($fh, $pi_config_tmp) = tempfile('pi-init-XXXXXXXX', DIR => $dir);
+
+# Now, we grab another lock to use git-config(1) locking, so it won't
+# wait on the lock, unlike some of our internal flock()-based locks.
+# This is to prevent direct git-config(1) usage from clobbering our
+# changes.
+my $lockfile = "$pi_config.lock";
+my $lockfh;
+sysopen($lockfh, $lockfile, O_RDWR|O_CREAT|O_EXCL) or do {
+	$lockfh = undef;
+	warn "could not open config file: $lockfile: $!\n";
+	exit(255);
+};
+END { unlink($lockfile) if $lockfh };
+
 my $perm;
 if (-e $pi_config) {
 	open(my $oh, '<', $pi_config) or die "unable to read $pi_config: $!\n";
diff --git a/t/init.t b/t/init.t
index 667b09fe..0cd6f31f 100644
--- a/t/init.t
+++ b/t/init.t
@@ -10,6 +10,8 @@ my $tmpdir = tempdir('pi-init-XXXXXX', TMPDIR => 1, CLEANUP => 1);
 use constant pi_init => 'blib/script/public-inbox-init';
 use PublicInbox::Import;
 use File::Basename;
+use PublicInbox::Spawn qw(spawn);
+use Cwd qw(getcwd);
 open my $null, '>>', '/dev/null';
 my $rdr = { 2 => fileno($null) };
 sub quiet_fail {
@@ -47,6 +49,16 @@ sub quiet_fail {
 	@cmd = (pi_init, 'clist', '-V2', "$tmpdir/clist",
 		   qw(http://example.com/clist clist@example.com));
 	quiet_fail(\@cmd, 'attempting to init V2 from V1 fails');
+
+	open my $lock, '+>', "$cfgfile.lock" or die;
+	@cmd = (getcwd(). '/'. pi_init, 'lock', "$tmpdir/lock",
+		qw(http://example.com/lock lock@example.com));
+	ok(-e "$cfgfile.lock", 'lock exists');
+	my $pid = spawn(\@cmd, undef, $rdr);
+	is(waitpid($pid, 0), $pid, 'lock init failed');
+	is($? >> 8, 255, 'got expected exit code on lock failure');
+	ok(unlink("$cfgfile.lock"),
+		'-init did not unlink lock on failure');
 }
 
 SKIP: {
-- 
EW