Permalink
Browse files

Update migration guide

  • Loading branch information...
1 parent 4e989ba commit 6c71d86c55e678f8aa61c4b77f1e77da441bfd18 @smfreegard smfreegard committed Nov 22, 2012
Showing with 42 additions and 2 deletions.
  1. +42 −2 docs/tutorials/Migrating_from_v1_to_v2.md
@@ -37,9 +37,49 @@ stream. The stream is called `transaction.message_stream`.
These changes may be complicated if you are iterating over each line and
doing something with the strings therein. However if you are piping the data
to an application or over a network, your code will become significantly
-simpler.
+simpler (and a lot faster).
+
+In v1.x Haraka populated the `transaction.data_lines` array for each line of
+data received. If you were writing the data to a socket then you had to handle
+backpressure manually by checking the return of `write()` and adding
+`on('drain')` handlers like so:
+
+ var data_marker = 0;
+ var in_data = false;
+ var end_pending = true;
+ var send_data = function () {
+ in_data = true;
+ var wrote_all = true;
+ while (wrote_all && (data_marker < connection.transaction.data_lines.length)) {
+ var line = connection.transaction.data_lines[data_marker];
+ data_marker++;
+ wrote_all = socket.write(new Buffer(line.replace(/^\./, '..').replace(/\r?\n/g, '\r\n')), 'binary');
+ if (!wrote_all) return;
+ }
+ // we get here if wrote_all still true, and we got to end of data_lines
+ if (end_pending) {
+ end_pending = false;
+ // Finished...
+ socket.send_command('dot');
+ }
+ };
+ socket.on('drain', function () {
+ if (end_pending && in_data) {
+ process.nextTick(function () { send_data() });
+ }
+ });
+
+In v2.x this now becomes:
+
+ connection.transaction.message_stream.pipe(socket, {dot_stuffing: true, ending_dot: true});
+
+This automatically chunks the data, handles backpressure and will apply any
+necessary format changes. See `docs/Transaction.md` for the full details.
-...
+If you need to handle the input data by line, then you will need to create
+your own writable stream and then pipe the message to the stream and then
+extract the lines from the stream of data. See `plugins/dkim_sign.js` for
+an example.
Fixing attachment_hooks plugins
-------------------------------

0 comments on commit 6c71d86

Please sign in to comment.