robertklep/node-mbox

mbox file parser for Node.js

node-mbox

mbox file parser for Node.js.

Backward incompatibility warning

From version 1.0.0 onwards, message data is passed around as Buffer instead of String.

You can call msg.toString([encoding]) to convert to a string, or explicitly set the encoding option (see below).

Install

From the NPM repository:

$ npm install node-mbox

From the Github repository:

$ git clone https://github.com/robertklep/node-mbox.git
$ cd node-mbox
$ npm install [-g]

Description

This module parses mbox files, as described here. Starting with version 0.1.0, it's pretty speedy, processing a 1.5GB mbox file in about 20 seconds.

Note that this module doesn't parse the mail messages themselves, for which other solutions exist (for example the quite able mailparser module from Andris Reinman).

Example

See the included example.js:

$ npm install mailparser
$ node example < test/test-4-message.mbox

Options

• encoding : output encoding (default: undefined, meaning message data is passed as Buffer)
• strict : enable strict mode (emits an error when input doesn't look like valid mbox data)
• stream: instead of collecting and emitting entire messages, emit a stream. This is useful if you want to process mailboxes that contain large messages (the aforementioned mailparser accepts message streams directly)

Usage

const Mbox = require('node-mbox');

// First, different types of instantiation:

// 1. pass it a filename
const mbox    = new Mbox('filename', { /* options */ });

// 2. pass it a string/buffer
const fs      = require('fs');
const mailbox = fs.readFileSync('filename');
const mbox    = new Mbox(mailbox, { /* options */ });

// 3. pass it a stream
const fs      = require('fs');
const stream  = fs.createReadStream('filename');
const mbox    = new Mbox(stream, { /* options */ });

// 4. pipe a stream to it
const mbox    = new Mbox({ /* options */ });
process.stdin.pipe(mbox);

// Next, catch events generated:
mbox.on('message', function(msg) {
  // `msg` is a `Buffer` instance
  console.log('got a message', msg.toString());
});

mbox.on('error', function(err) {
  console.log('got an error', err);
});

mbox.on('end', function() {
  console.log('done reading mbox file');
});

Streaming example:

const mbox = new Mbox({ stream : true });

// `message` event emits stream
mbox.on('message', function(stream) {
  stream.on('data', function(chunk) {
    ...
  }).on('end', function() {
    ...
  });
});

process.stdin.pipe(mbox);

Testing

There is a limited number of tests:

$ cd /path/to/node-mbox/
$ npm test

License

MIT

node-mbox's Issues

stream.on is not a function error

The streaming example given in the documentation doesn't seem to work/ throws a "stream.on is not a function" error. What am I missing here?

`const mbox = new Mbox({ streaming : true });

// message event emits stream
mbox.on('message', function(stream) {
stream.on('data', function(chunk) {
...
}).on('end', function() {
...
});
});

process.stdin.pipe(mbox);`

Use with await? Or backpressure? Need to slow down "message" event so I can process them

I'm unable to slow down the "message" event so that it can wait for processing to happen. The examples shown don't seem to pass a "done()" to the "message" event handler for async coordination.

So if my message processing needs a moment, the messages build up and I need to either drop them or store them in memory. I'm operating on a large 40GB mbox file.

Please advise

Any file return one message

var mbox    = new Mbox('blackbox.psd');
mbox.on('message', function(msg) {
  console.log('got a message', msg);
});

any file return 1 message, aslo if it not have text 'From'

msg = ' From ' + content of blackbox.psd

Bug

Hi, the current implementation of splitting the mbox file into emls is looking for line that starts with 'From ' . I had eml's that in their text had lines that started with 'From ', and had nothing to do with mbox splitter. That caused bugs - broken messages. You need to check more values in that line, for example that it ends with a date. Provided mbox file with example to the issue.
test.mbox.zip

Piping to mailparser

I am trying to pipe mbox to mailparser, but it does not work. I am a noob in Nodejs streams, but it seems to me that mbox does not support piping out to another stream. Could you please provide me some hints?

Large Message Crash

If a message is bigger than the V8 string length limit (Math.pow(2, 28), ~260mb) the parser will crash with following error:

node_modules/node-mbox/src/mbox.js:100
        stream.emit('message', 'From ' + chunks.join(''));
                                                ^

RangeError: Invalid string length
    at Array.join (native)
    at SBMH.<anonymous> (node_modules/node-mbox/src/mbox.js:100:49)
    at emitMany (events.js:146:13)
    at SBMH.emit (events.js:223:7)
    at SBMH._sbmh_feed (node_modules/streamsearch/lib/sbmh.js:159:14)
    at SBMH.push (node_modules/streamsearch/lib/sbmh.js:56:14)
    at MboxStream._transform (node_modules/node-mbox/src/mbox.js:119:17)
    at MboxStream.Transform._read (_stream_transform.js:186:10)
    at MboxStream.Transform._write (_stream_transform.js:174:12)
    at doWrite (_stream_writable.js:387:12)

A potential mitigation strategy:
https://gist.github.com/tpreusse/bc2ccf6fc6bf4ff563cdd336c1728db2/revisions#diff-05028f8355c8d7379cb42b5feac6429f
(throw error by default, skip or emit partial via options)

However the ultimate solution would be create a new api which allows to stream junks (e.g. to mailparser) as they come in. mailparser can probably handle almost unlimited attachment sizes with its attachment streams.