HTTP Request in Editor Implementation

What is this?

JetBrains company has come up with with very interesting concept called HTTP Request in Editor Spec. They implemented this spec into their IDEs. You are able to create files with .http extensions with nice syntax highlighting and run HTTP requests directly in your editor. Eventually you can create collection of these .http files, check them in as part of your codebase and share them with the rest of your team. This is really great...but...

There is currently no CLI runner for .http files. From the moment we checked our .http files inside our project we should test if those file reflect reality. This project provides tool for running .http files on your CI.

Warning: Currently we have only implemented the parser which creates documented CST. We're working hard on implementation of runner compatible with JetBrains one. Stay tuned for the runner!

This repo contains reference implementation of HTTP Request in Editor Spec parser.

The HTTP Request in Editor Spec is using context-free grammar to present set of production rules. We're using nearley to declaratively map this grammar and generate a JavaScript parser from it.

Parser can parse following syntax and creates CST that can be consumed and executed by various runtime environments. I'll provide a reference implementation of a reference runtime implementation as soon as the parser is finished.

### request 1
POST https://httpbin.org/post HTTP/1.1
Authorization: token

request body 1

### request 2
POST https://httpbin.org/post HTTP/2.0
Authorization: token2

{
  "test": 3,
  "a": "b"
}

### request 3
POST https://httpbin.org/post HTTP/3.0
Authorization: token3

{}

###

Installation

 $ npm i http-request-in-editor

Parser

const { parse } = require('http-request-in-editor');


const http = `
POST https://httpbin.org/post

###
`;

const cst = parse(http);
// now process the CST with your favorite http library

CST

Parser is producing JSON serializable CST. Following HTTP Request in Editor fragment

### post request
POST http://www.example.com HTTP/2.0
# comment
Authorization: token

message body

> {% script %}
<> ./file.json

###

will produce following CST:

(requests-file
  (request
    (requests-line
      (method)
      (request-target
        (absolute-form
          (scheme)
          (literal)
          (hier-part
            (authority
              (host
                (ipv4-or-reg-name))))))
      (http-version))
    (headers
      (header-field
        (field-name)
        (field-value)))
    (message-body
      (messages
        (message-line)
        (message-line)))
    (response-handler
      (handler-script))
    (response-ref
      (file-path))))

CST should be self-explanatory. For more information checkout our CST Types.

Runner

const fs = require('fs');
const { runSpec } = require('http-request-in-editor');

const spec = fs.readFileSync('./spec-file.http');
const result = await runSpec(spec); // returns list of response objects

Development

Fork the repo, clone in and install by

 $ npm i

Edit src/parser/grammer.ne and create a grammar that maps to HTTP Request in Editor Spec.

Compiles src/parser/grammar.ne file into src/parser/grammar.js.

 $ npm run compile

Test parser grammar against predefined fixtures.

 $ npm test

Generate railroad diagrams from src/parser/grammar.ne file.

 $ npm run railroad

Generate random strings that satisfy the grammar defined insrc/parser/grammar.ne file.

 $ npm run unparse

Regenerates Corpus file. Replaces CST S-expression representation with the new one.

 $ npm run corpus:regenerate

Lint the source code.

 $ npm run lint

Notes

1. Multipart-form-data will not be part of resulting CST. It's just a special shape of message-body and requires no special handling even during runtime.

Missing features

• Environment variables