* [PATCH 1/2] import: document API for public consumption
2016-04-28 2:00 7% [PATCH 0/2] import: public API and dumb HTTP enforcement Eric Wong
@ 2016-04-28 2:00 4% ` Eric Wong
0 siblings, 0 replies; 2+ results
From: Eric Wong @ 2016-04-28 2:00 UTC (permalink / raw)
To: meta
This is probably trivial enough to be final?
---
Documentation/include.mk | 2 +-
lib/PublicInbox/Git.pm | 54 +++++++++++++++++++-
lib/PublicInbox/Import.pm | 127 ++++++++++++++++++++++++++++++++++++++++++++--
t/import.t | 2 +-
4 files changed, 178 insertions(+), 7 deletions(-)
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 4669ac5..9427887 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -6,7 +6,7 @@ RSYNC = rsync
RSYNC_DEST = public-inbox.org:/srv/public-inbox/
docs := README COPYING INSTALL TODO $(shell git ls-files 'Documentation/*.txt')
INSTALL = install
-POD2MAN = pod2man
+POD2MAN ?= pod2man
POD2MAN_OPTS = -v --stderr -d 1994-10-02 -c 'public-inbox user manual'
pod2man = $(POD2MAN) $(POD2MAN_OPTS)
POD2TEXT = pod2text
diff --git a/lib/PublicInbox/Git.pm b/lib/PublicInbox/Git.pm
index c406c03..d821182 100644
--- a/lib/PublicInbox/Git.pm
+++ b/lib/PublicInbox/Git.pm
@@ -3,7 +3,7 @@
#
# Used to read files from a git repository without excessive forking.
# Used in our web interfaces as well as our -nntpd server.
-# This is based on code in Git.pm which is GPLv2, but modified to avoid
+# This is based on code in Git.pm which is GPLv2+, but modified to avoid
# dependence on environment variables for compatibility with mod_perl.
# There are also API changes to simplify our usage and data set.
package PublicInbox::Git;
@@ -134,3 +134,55 @@ sub cleanup {
sub DESTROY { cleanup(@_) }
1;
+__END__
+=pod
+
+=head1 NAME
+
+PublicInbox::Git - git wrapper
+
+=head1 VERSION
+
+version 1.0
+
+=head1 SYNOPSIS
+
+ use PublicInbox::Git;
+ chomp(my $git_dir = `git rev-parse --git-dir`);
+ $git_dir or die "GIT_DIR= must be specified\n";
+ my $git = PublicInbox::Git->new($git_dir);
+
+=head1 DESCRIPTION
+
+Unstable API outside of the L</new> method.
+It requires L<git(1)> to be installed.
+
+=head1 METHODS
+
+=cut
+
+=head2 new
+
+ my $git = PublicInbox::Git->new($git_dir);
+
+Initialize a new PublicInbox::Git object for use with L<PublicInbox::Import>
+This is the only public API method we support. Everything else
+in this module is subject to change.
+
+=head1 SEE ALSO
+
+L<Git>, L<PublicInbox::Import>
+
+=head1 CONTACT
+
+All 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/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2016 all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
+
+=cut
diff --git a/lib/PublicInbox/Import.pm b/lib/PublicInbox/Import.pm
index 8dd11d0..f9c05da 100644
--- a/lib/PublicInbox/Import.pm
+++ b/lib/PublicInbox/Import.pm
@@ -66,7 +66,7 @@ sub now2822 () {
}
# returns undef on non-existent
-# (-1, msg) on mismatch
+# ('MISMATCH', msg) on mismatch
# (:MARK, msg) on success
sub remove {
my ($self, $mime) = @_; # mime = Email::MIME
@@ -76,13 +76,13 @@ sub remove {
my ($r, $w) = $self->gfi_start;
my $tip = $self->{tip};
- return if $tip eq '';
+ return ('MISSING', undef) if $tip eq '';
print $w "ls $tip $path\n" or wfail;
local $/ = "\n";
my $check = <$r>;
defined $check or die "EOF from fast-import / ls: $!";
- return if $check =~ /\Amissing /;
+ return ('MISSING', undef) if $check =~ /\Amissing /;
$check =~ m!\A100644 blob ([a-f0-9]{40})\t!s or die "not blob: $check";
my $blob = $1;
print $w "cat-blob $blob\n" or wfail;
@@ -107,7 +107,7 @@ sub remove {
my $cur = Email::MIME->new($buf);
if ($cur->header('Subject') ne $mime->header('Subject') ||
$cur->body ne $mime->body) {
- return (-1, $cur);
+ return ('MISMATCH', $cur);
}
my $ref = $self->{ref};
@@ -215,3 +215,122 @@ sub done {
}
1;
+__END__
+=pod
+
+=head1 NAME
+
+PublicInbox::Import - message importer for public-inbox
+
+=head1 VERSION
+
+version 1.0
+
+=head1 SYNOPSYS
+
+ use Email::MIME;
+ use PublicInbox::Git;
+ use PublicInbox::Import;
+
+ chomp(my $git_dir = `git rev-parse --git-dir`);
+ $git_dir or die "GIT_DIR= must be specified\n";
+ my $git = PublicInbox::Git->new($git_dir);
+ my @committer = ('inbox', 'inbox@example.org');
+ my $im = PublicInbox::Import->new($git, @committer);
+
+ # to add a message:
+ my $message = "From: <u\@example.org>\n".
+ "Subject: test message \n" .
+ "Date: Thu, 01 Jan 1970 00:00:00 +0000\n" .
+ "Message-ID: <m\@example.org>\n".
+ "\ntest message";
+ my $parsed = Email::MIME->new($message);
+ my $ret = $im->add($parsed);
+ if (!defined $ret) {
+ warn "duplicate: ",
+ $parsed->header_obj->header_raw('Message-ID'), "\n";
+ } else {
+ print "imported at mark $ret\n";
+ }
+ $im->done;
+
+ # to remove a message
+ my $junk = Email::MIME->new($message);
+ my ($mark, $orig) = $im->remove($junk);
+ if ($mark eq 'MISSING') {
+ print "not found\n";
+ } elsif ($mark eq 'MISMATCH') {
+ print "Message exists but does not match\n\n",
+ $orig->as_string, "\n",;
+ } else {
+ print "removed at mark $mark\n\n",
+ $orig->as_string, "\n";
+ }
+ $im->done;
+
+=head1 DESCRIPTION
+
+An importer and remover for public-inboxes which takes L<Email::MIME>
+messages as input and stores them in a ssoma repository as
+documented in L<https://ssoma.public-inbox.org/ssoma_repository.txt>,
+except it does not allow duplicate Message-IDs.
+
+It requires L<git(1)> and L<git-fast-import(1)> to be installed.
+
+=head1 METHODS
+
+=cut
+
+=head2 new
+
+ my $im = PublicInbox::Import->new($git, @committer);
+
+Initialize a new PublicInbox::Import object.
+
+=head2 add
+
+ my $parsed = Email::MIME->new($message);
+ $im->add($parsed);
+
+Adds a message to to the git repository. This will acquire
+C<$GIT_DIR/ssoma.lock> and start L<git-fast-import(1)> if necessary.
+
+Messages added will not be visible to other processes until L</done>
+is called, but L</remove> may be called on them.
+
+=head2 remove
+
+ my $junk = Email::MIME->new($message);
+ my ($code, $orig) = $im->remove($junk);
+
+Removes a message from the repository. On success, it returns
+a ':'-prefixed numeric code representing the git-fast-import
+mark and the original messages as an Email::MIME object.
+If the message could not be found, the code is "MISSING"
+and the original message is undef. If there is a mismatch where
+the "Message-ID" is matched but the subject and body do not match,
+the returned code is "MISMATCH" and the conflicting message
+is returned as orig.
+
+=head2 done
+
+Finalizes the L<git-fast-import(1)> and unlocks the repository.
+Calling this is required to finalize changes to a repository.
+
+=head1 SEE ALSO
+
+L<Email::MIME>
+
+=head1 CONTACT
+
+All 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/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2016 all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
+
+=cut
diff --git a/t/import.t b/t/import.t
index 6918484..09c0036 100644
--- a/t/import.t
+++ b/t/import.t
@@ -57,7 +57,7 @@ is(undef, $im->remove($mime), 'remove is idempotent');
# mismatch on identical Message-ID
$mime->header_set('Message-ID', '<a@example.com>');
($mark, $msg) = $im->remove($mime);
-is($mark, -1, 'mark == -1 on mismatch');
+is($mark, 'MISMATCH', 'mark == MISMATCH on mismatch');
is($msg->header('Message-ID'), '<a@example.com>', 'Message-ID matches');
isnt($msg->header('Subject'), $mime->header('Subject'), 'subject mismatch');
--
EW
^ permalink raw reply related [relevance 4%]
* [PATCH 0/2] import: public API and dumb HTTP enforcement
@ 2016-04-28 2:00 7% Eric Wong
2016-04-28 2:00 4% ` [PATCH 1/2] import: document API for public consumption Eric Wong
0 siblings, 1 reply; 2+ results
From: Eric Wong @ 2016-04-28 2:00 UTC (permalink / raw)
To: meta
It's become clear that our Import module is useful for customizing
importers (e.g. to strip auto-added signature tags); so document
it as a stable public API. While we're at it, enforce
"git update-server-info" so serving dumb HTTP clone will always
be possible.
Eric Wong (2):
import: document API for public consumption
import: run git-update-server-info when done
Documentation/include.mk | 2 +-
lib/PublicInbox/Git.pm | 54 ++++++++++++++++-
lib/PublicInbox/Import.pm | 144 +++++++++++++++++++++++++++++++++++++++++++---
script/public-inbox-index | 2 -
script/public-inbox-mda | 4 --
t/import.t | 2 +-
6 files changed, 190 insertions(+), 18 deletions(-)
^ permalink raw reply [relevance 7%]
Results 1-2 of 2 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2016-04-28 2:00 7% [PATCH 0/2] import: public API and dumb HTTP enforcement Eric Wong
2016-04-28 2:00 4% ` [PATCH 1/2] import: document API for public consumption Eric Wong
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).