partly

Partly

This module is meant to be a simple, extensible, "multipart" payload encoder and decoder. It complies with the official grammar specification located here:

• http://tools.ietf.org/html/rfc822
• http://tools.ietf.org/html/rfc2045
• http://tools.ietf.org/html/rfc2046
• http://tools.ietf.org/html/rfc2047
• http://tools.ietf.org/html/rfc2048
• http://tools.ietf.org/html/rfc2049

The RFC documents are also bundled with this project.

Assumptions made for simplicity:

• RFC 822 header fields have unstructured s and s.
• RFC 822 header fields may be in any order.
• RFC 2045 defined header fields are RFC 822 grammar compliant.
• RFC 2045 defined header fields all begin with "Content-".
• RFC 2046 composite media type, "multipart", must include a global boundary parameter.
• RFC 2046 composite media type, "multipart", encoders must not generate transport padding (WSP).
• RFC 2046 composite media type, "multipart", decoders must gracefully handle transport padding (WSP).
• RFC 2046 composite media type, "multipart", decoders must ignore or discard any preamble or epilogue.
• RFC 2046 composite media type, "multipart", body parts must use RFC 822 message syntax.
• RFC 2046 composite media type, "multipart", body parts must allow for optional header fields.
• RFC 2046 composite media type, "multipart", body parts must make no semantic assumption regarding header fields.
• RFC 2046 composite media type, "multipart", body parts must not contain the boundary delimiter.

Lexical Tokens:

CHAR  = <any ASCII character>                                           ; ( 0-127, %x00-7F )
ALPHA = <any ASCII alphabetic character>                                ; ( 65-90 / 97-122, %x41-5A / %x61-7A )
DIGIT = <any ASCII decimal digit>                                       ; ( 48-57, %x30-39 )
CTL   = <any ASCII control character and DEL>                           ; ( 0-31 / 127, %x00-1F / %x7F )
CR    = <ASCII CR, carriage return>                                     ; ( 13, %x0D )
LF    = <ASCII LF, linefeed>                                            ; ( 10, %x0A )
SPACE = <ASCII SP, space>                                               ; ( 32, %x20 )
HTAB  = <ASCII HT, horizontal-tab>                                      ; ( 09, %x09 )
CRLF  = CR LF                                                           ; ( 13 10, %x0D %x0A )
WSP   = SPACE / HTAB                                                    ; ( 32 / 09, %x20 %x09 )
OCTET = <any 0-255 octet value>                                         ; ( 0-255, %x00-FF )
text  = <any CHAR, including bare CR & bare LF, but NOT including CRLF>

RFC 822 Header Fields BNF:

field-name = 1*<any CHAR, excluding CTLs, SPACE, and ":">
field-body = *text [CRLF WSP field-body]
field      = field-name ":" [field-body] CRLF

RFC 2046 "Multipart" Boundary BNF:

bcharsnospace = DIGIT / ALPHA / "'" / "(" / ")" / "+" / "_" / "," / "-" / "." / "/" / ":" / "=" / "?"
bchars        = bcharsnospace / " "
boundary      = 0*69<bchars> bcharsnospace

RFC 2046 "Multipart" Body BNF:

body-part      = *field [CRLF *OCTET]
multipart-body = [*(*text CRLF) *text CRLF]                ; Optional Preamble
                 "--" boundary *WSP CRLF                   ; --F6Rxhi'v4e)(fn
                 body-part                                 ; Content-Type: application/json
                                                           ;
                                                           ; {"cool":"stuff"}
                 *(CRLF "--" boundary *WSP CRLF body-part) ; --F6Rxhi'v4e)(fn
                                                           ; Content-Type: application/json
                                                           ;
                                                           ; {"cool":"other stuff"}
                 CRLF "--" boundary "--" *WSP              ; --F6Rxhi'v4e)(fn--
                 [CRLF *(*text CRLF) *text]                ; Optional Epilogue

A Complex Multipart Example:

This message contains five parts that are to be displayed serially:

• 2 introductory plain text objects
• 1 embedded multipart message
• 1 text/enriched object
• 1 closing encapsulated text message in a non-ASCII character set

The embedded multipart message itself contains two objects to be displayed in parallel:

• 1 picture

• 1 audio fragment

  MIME-Version: 1.0 From: Nathaniel Borenstein [e-mail] To: Ned Freed [e-mail] Date: Fri, 07 Oct 1994 16:15:05 -0700 (PDT) Subject: A multipart example Content-Type: multipart/mixed; boundary=unique-boundary-1

  This is the preamble area of a multipart message. Mail readers that understand multipart format should ignore this preamble.

  If you are reading this text, you might want to consider changing to a mail reader that understands how to properly display multipart messages.

  --unique-boundary-1

  ... Some text appears here ...

  [Note that the blank between the boundary and the start of the text in this part means no header fields were given and this is text in the US-ASCII character set. It could have been done with explicit typing as in the next part.]

  --unique-boundary-1 Content-type: text/plain; charset=US-ASCII

  This could have been part of the previous part, but illustrates explicit versus implicit typing of body parts.

  --unique-boundary-1 Content-Type: multipart/parallel; boundary=unique-boundary-2

  --unique-boundary-2 Content-Type: audio/basic Content-Transfer-Encoding: base64

  ... base64-encoded 8000 Hz single-channel mu-law-format audio data goes here ...

  --unique-boundary-2 Content-Type: image/jpeg Content-Transfer-Encoding: base64

  ... base64-encoded image data goes here ...

  --unique-boundary-2--

  --unique-boundary-1 Content-type: text/enriched

  This is enriched. as defined in RFC 1896

  Isn't it cool?

  --unique-boundary-1 Content-Type: message/rfc822

  From: (mailbox in US-ASCII) To: (address in US-ASCII) Subject: (subject in US-ASCII) Content-Type: Text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: Quoted-printable

  ... Additional text in ISO-8859-1 goes here ...

  --unique-boundary-1--

Installation

npm install partly --save

Usage

/**
 * Module Dependencies.
 */
var partly = require('partly'),
    mp = partly.multipart,
    bp = partly.bodypart;

var body = mp('mixed');

console.log(
    body
        .addBodyPart(
            bp()
                .setType('application/json')
                .setPayload('{}')
        ).toString()
);

Tests

No unit tests are currently present. Eventually:

npm test

Contributing

In lieu of a formal style guideline, take care to maintain the existing coding style.