Update data_post_headers doc (#259)

* Update data_post_headers documentation
We cannot reject at this stage, which is only there to alter headers.
Fix #258

* DMARC plugin: reject in data_post
Followup of #258: we cannot reject a connection during data_post_headers. So add a new hook in data_post to do the real rejection

docs/hooks.md

@@ -343,26 +343,20 @@ __FIXME:__ check arguments
 
 The `data_post_headers` hook is called after the client sends the final .\r\n of
 a message and before the message is processed by `data_post`. This hook is
-primarily used by plugins that insert new headers (ex: Received-SPF) and/or
+used by plugins that insert new headers (ex: Received-SPF) and/or
 modify headers such as appending to Authentication-Results (SPF, DKIM, DMARC).
 
 When it is desirable to have these header modifications evaluated by filtering
 software (spamassassin, dspam, etc.) running on `data_post`, this hook should be
 used instead of `data_post`.
 
+Note that you cannot reject in this hook, use the data_post hook instead
+
 Allowed return codes are
 
-- DENY
+- DECLINED
 
-    Return a hard failure code
+    Do nothing
-
-- DENYSOFT
-
-    Return a soft failure code
-
-- DENY\_DISCONNECT / DENYSOFT\_DISCONNECT
-
-    as above but with disconnect
 
 ## hook\_data\_post
 

plugins/dmarc

@@ -102,6 +102,7 @@ sub register {
     else {
         $self->{_dmarc} = Mail::DMARC::PurePerl->new();
         $self->register_hook('data_post_headers', 'check_dmarc');
+        $self->register_hook('data_post', 'reject_dmarc');
     };
 }
 
@@ -189,6 +190,13 @@ sub check_dmarc {
     return DECLINED if $self->is_immune;
 
     $self->adjust_karma(-3);
-# at what point do we reject?
+    # Add a mark now so the data_post hook can do the real reject
-    return $self->get_reject("failed DMARC policy");
+    $self->connection->notes('reject_dmarc', '1');
+}
+
+sub reject_dmarc {
+    my ($self, $transaction) = @_;
+    return $self->get_reject("failed DMARC policy")
+        if ($self->connection->notes('reject_dmarc'));
+    return DECLINED;
 }