Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@vltr
vltr committed Aug 1, 2014
1 parent 0b0088b commit e7a5bfc
Showing 1 changed file with 97 additions and 84 deletions.
181 changes: 97 additions & 84 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,118 +1,131 @@
txmilter
========

The milter protocol written in pure python as a twisted protocol!
All under GNU GPLv2!
The milter protocol written in pure python as a twisted protocol, licensed under [GPLv2!](../master/LICENSE)

####What?
##wait, what?

The txmilter is a project that aims to bring milter as a reactor, to do that
twisted framework for python is perfect, it abstracts all connections and all
asynchronous operations needed to archive this.
The **txmilter** is a project that aims to bring the milter protocol to python using the [Twisted Matrix Framework](https://twistedmatrix.com/trac/). It was inspired after people telling us to use [crochet](https://pypi.python.org/pypi/crochet/) and libmilter to achieve our goals. As we like to use things inside Twisted the way Twisted works, it was decided to create this project.

The goal of using txmilter is to provide a _faster_ response using the power of
asynchronous server instead the threaded solution used by libmilter. Txmilter is
_really fast_ and can handle _lots_ of simultaneous connections thanks to twisted.
The goal of using **txmilter** is to provide a _faster_ response using Twisted's power of asynchronous calls instead the threaded solution used by libmilter. **txmilter** is _really fast_ and can handle _lots_ of simultaneous connections. In pure python ;)

###How do I use it?
###how do I use it?

txmilter is designed to be as simple as possible, and as close as possible to
libmilter (that you can check here: HTTPS://www.milter.org/developers/api/),
having that in mind, if you know how libmilter works you won't get any trouble
working with txmilter. Function calls are (_almost_) the same and functions
names really remembers libmilter name calls.
first, you'll have to install it using pip or from [PyPI](https://pypi.python.org/pypi):

```
$ pip install txmilter
```

**txmilter** is designed to be as simple as possible, and as close as possible to libmilter (that you can check here: HTTPS://www.milter.org/developers/api/), having that in mind, if you know how libmilter works you won't get any trouble
working with txmilter. Function calls are (_almost_) the same and functions names really remembers libmilter name calls.

For example, take a close look to the code:


```
#!/usr/bin/python
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
from twisted.internet import reactor
from protocol import MilterProtocolFactory
from defaults import MilterFactory
from txmilter.protocol import MilterProtocolFactory
from txmilter.defaults import MilterFactory
def main():
reactor.listenTCP( 1234, MilterProtocolFactory(
# we consider a "good pattern" to import reactor just when you'll use it,
# since we have other reactors in our codebase
from twisted.internet import reactor
reactor.listenTCP(1234, MilterProtocolFactory(
MilterFactory()
) )
))
reactor.run()
if __name__ == '__main__':
main()
```

This is _just_ a twisted protocol inicialization as any twisted program will do...
This is _just_ a twisted protocol inicialization as any twisted protocol will do ...

`MilterFactory` is a just a empty factory that builds `Milter` objects. You should
build your own factory to instantiate your own milter objects. The MilterProtocolFactory
is what do all the magic for you, it abstracts the communication to give you the
`Milter` interface.
`MilterFactory` is just an empty factory that creates `Milter` objects. You should build your own factory to instantiate your milter objects. The `MilterProtocolFactory` is the one that does the magic for you, abstracting communication to expose you the `Milter` interface.

Your job is to extend `Milter`, override the method that you need to work with,
override the `xxfi_negotiate` to signal to the exchange what you plan to support
and build a `MilterFactory`.
Your job is to extend `Milter`, override any method you need to work with _and_ the `xxfi_negotiate` method to exchange what signals your milter will support to build a `MilterFactory`.

For a plus, one txmilter program can handle more than one milter plugin on the
same connection, taking care of handling any signal different from continue and
communicating the MTA.
As a plus, the **txmilter** can handle more than one milter plugin on the same connection, taking care of handling any signal different from continue and communicating with the MTA.


```
MTA txmilter your milter plugin
_____________________________
| |
| MTA Opens Connection |
|____________________________|
| _____________________________
| | |
|_________________> | Instantiate all plugins |
|____________________________|
_____________________________ |
| | |
| MTA Starts Negotiation | <_____________|
|____________________________|
| _____________________________
| | |
|___________________________________________________> | Send flags |
|____________________________|
|
_____________________________ |
| | |
| Merge flags | <____________|
|____________________________|
|
_____________________________ |
| | |
| Status filtering request | <________________|
|____________________________|
|
| _____________________________
| | |
|___________________________________________________> | Process And reply |
|____________________________|
|
_________________________________ |
| | |
| Wait all finish or first error | <__________|
|________________________________|
|
V
_________________________________
| |
| Reply Status |
|________________________________|
|
V
_________________________________________________________________________________________________________________
| |
| Close connection......... |
|________________________________________________________________________________________________________________|
MTA txmilter your milter
___________________
| |
| MTA opens |
| connection |
|__________________|
| __________________
| | |
|_________> | Instantiate |
| all plugins |
|_________________|
___________________ |
| | |
| MTA starts | |
| negotiation | <_________|
|__________________|
| ____________________
| | |
|________________________________> | Send flags |
|___________________|
|
__________________ |
| | |
| Merge flags | <_________|
|_________________|
|
___________________ |
| | |
| Status filtering | |
| request | <_________|
|__________________|
|
| ____________________
| | |
|________________________________> | Process and reply |
|___________________|
|
__________________ |
| | |
| Wait all finish | |
| or first error | <_________|
|_________________|
|
V
__________________
| |
| Reply status |
|_________________|
|
V
_________________________________________________________________
| |
| Close connection |
|________________________________________________________________|
```

and that all :)

#todo

* we still have no test units and code coverage, but you're welcome to push them if you want :)
* docs: wow, better examples and sphinx related docs are still pending;
* py3 was just completely ignored for now.


#license

**txmilter** code and docs are released under the [GPLv2](../master/LICENSE) license, from which is derived from the libmilter license - as we used its code as a base for ours and also as a form of gratitude.

0 comments on commit e7a5bfc

Please sign in to comment.