Skip to content
This repository
Browse code

Improve plugin documentation

  • Loading branch information...
commit d3e278efc035949309fda997d56f8db938ef331a 1 parent 8b2fd3c
Steve Freegard smfreegard authored

Showing 1 changed file with 37 additions and 0 deletions. Show diff stats Hide diff stats

  1. +37 0 docs/Plugins.md
37 docs/Plugins.md
Source Rendered
@@ -173,6 +173,43 @@ If a rcpt plugin DOES call `next(OK)` then the `rcpt_ok` hook is run. This
173 173 is primarily used by the queue/smtp_proxy plugin which needs to run after
174 174 all rcpt hooks.
175 175
  176 +Sharing State
  177 +-------------
  178 +
  179 +There are several cases where you might need to share information between
  180 +plugins. This is done using `notes` - there are three types available:
  181 +
  182 +* server.notes
  183 +
  184 + Available in all plugins. This is created at PID start-up and is shared
  185 + amongst all plugins on the same PID and listener.
  186 + Typical uses for notes at this level would be to share database
  187 + connections between multiple plugins or connection pools etc.
  188 +
  189 +* connection.notes
  190 +
  191 + Available on any hook that passes 'connection' as a function parameter.
  192 + This is shared amongst all plugins for a single connection and is
  193 + destroyed after the client disconnects.
  194 + Typical uses for notes at this level would be to store information
  195 + about the connected client e.g. rDNS names, HELO/EHLO, white/black
  196 + list status etc.
  197 +
  198 +* connection.transaction.notes
  199 +
  200 + Available on any hook that passes 'connection' as a function parameter
  201 + between hook_mail and hook_data_post.
  202 + This is shared amongst all plugins for this transaction (e.g. MAIL FROM
  203 + through until a message is received or the connection is reset).
  204 + Typical uses for notes at this level would be to store information
  205 + on things like greylisting which uses client, sender and recipient
  206 + information etc.
  207 +
  208 +All of these notes are simply a Javascript object underneath - so you use
  209 +them like a simple key/value store e.g.
  210 +
  211 + connection.transaction.notes.test = 'testing';
  212 +
176 213 Further Reading
177 214 --------------
178 215

0 comments on commit d3e278e

Please sign in to comment.
Something went wrong with that request. Please try again.