Metadata-Version: 2.1
Name: rfc-http-validate
Version: 0.3.4
Summary: DESCRIPTION
Author-email: Mark Nottingham <mnot@mnot.net>
License: Copyright (c) 2020 Mark Nottingham
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: homepage, https://github.com/mnot/rfc-http-validate/
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: http-sf >=1.0.1
Requires-Dist: blessings
Requires-Dist: commonmark
Provides-Extra: dev
Requires-Dist: mypy ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-md ; extra == 'dev'
Requires-Dist: validate-pyproject ; extra == 'dev'
Requires-Dist: build ; extra == 'dev'
Requires-Dist: types-commonmark ; extra == 'dev'

# rfc-http-validate

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Validating HTTP Messages in Markdown](#validating-http-messages-in-markdown)
- [Validating HTTP Messages in RFC XML](#validating-http-messages-in-rfc-xml)
- [Configuring Structured Type Information for Fields](#configuring-structured-type-information-for-fields)
- [Installation](#installation)
- [Use with I-D-Template](#use-with-i-d-template)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->


This is a simple script to validate HTTP messages (possibly containing [Structured Fields](https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html)) in [xml2rfcv3](https://tools.ietf.org/html/rfc7991) documents and [kramdown-rfc](https://github.com/cabo/kramdown-rfc) documents.

It checks that the content of an HTTP message:

* Optionally, starts with a valid HTTP/1.1 request or status line
* Has one or more HTTP/1.1 header field lines, possibly with line folding (so that long lines can be formatted within the constraints of the RFC format)
* Optionally, has a response body, separated from the header fields with a single empty line

The start line will be checked that the method or status code is reasonable, and that the version identifier `HTTP/1.1` is correct. The URL in requests will not be validated, however.

Header fields will be validated for general syntax. Additionally, header field names that are configured with structured type information (see below) will be validated according to that type.

The body, if present, is currently ignored (i.e., the `Content-Length` is not checked).

If an [RFC8792](https://www.rfc-editor.org/rfc/rfc8792.html) `\\` wrapping header is present, lines will be unwrapped first (i.e., before unfolding, as per above). This is useful for long lines with binary content (which cannot contain whitespace); e.g.,

~~~ xml
<sourcecode type="http-message">
# NOTE: '\' line wrapping per RFC 8792

Signature: sig1=:K2qGT5srn2OGbOIDzQ6kYT+ruaycnDAAUpKv+ePFfD0RAxn/1BUe\
    Zx/Kdrq32DrfakQ6bPsvB9aqZqognNT6be4olHROIkeV879RrsrObury8L9SCEibe\
    oHyqU/yCjphSmEdd7WD+zrchK57quskKwRefy2iEC5S2uAH0EPyOZKWlvbKmKu5q4\
    CaB8X/I5/+HLZLGvDiezqi6/7p2Gngf5hwZ0lSdy39vyNMaaAT0tKo6nuVw0S1MVg\
    1Q7MpWYZs0soHjttq0uLIA3DIbQfLiIvK6/l0BdWTU7+2uQj7lBkQAsFZHoA96ZZg\
    FquQrXRlmYOh+Hx5D9fJkXcXe5tmAg==:
</sourcecode>
~~~


## Validating HTTP Messages in Markdown

In Markdown, all you need to do is adorn your messages with `http-messsage`; for example:

~~~~
~~~ http-message
HTTP/1.1 200 OK
Foo: bar, baz
~~~
~~~~

Then, run:

> rfc-http-validate my-draft.md


## Validating HTTP Messages in RFC XML

In XML, this script examines all `sourcecode` and `artwork` elements; when one has a `type` of
`http-message`.

For example,

~~~ xml
<sourcecode type="http-message">
Foo: bar; baz
Foo: one,
     two
</sourcecode>
~~~

Then, run:

> rfc-http-validate my-draft.xml

Note that in your XML, there **must not be any whitespace** at the start of lines, unless they're continuation of previous lines (folding, as seen above).



## Configuring Structured Type Information for Fields

By default, the types of existing Structured Fields (including those that are compatible with Structured Fields; see [Retrofit Structured Fields for HTTP](https://datatracker.ietf.org/doc/draft-ietf-httpbis-retrofit/)) are known. Type information for other fields can be added on the command line or through a file.

To pass a type on the command line, use the `--list`, `--dictionary` or `--item` arguments as appropriate, followed by the field name. For example:

> rfc-http-validate --list Foo --list Bar --item Baz my_draft.xml

Here, `Foo` and `Bar` will be validated as Structured Lists, while `Baz` will be validated as a Structured Item.

Alternatively, you can collect this information in a JSON file, with the top-level object keys being field names, and their values being `list`, `dict` or `item` as appropriate. Thus, the configuration in the example above could be expressed in a JSON file `sf.json` as:

~~~ json
{
  "Foo": "list",
  "Bar": "list",
  "Baz": "item"
}
~~~

... and passed to the script like this:

> rfc-http-validate --map sf.json my_draft.xml


## Installation

The script requires Python 3, and can be installed with pip:

> pip3 install rfc-http-validate


## Use with I-D-Template

To automatically lint files with MT's [I-D-Template](https://github.com/martinthomson/i-d-template):

1. Add `rfc-http-validate` to `requirements.txt` (creating it if necessary)
2. Add a `sf.json` file containing the field(s) your draft uses mapped to one of `item`, `list`, or `dict`
3. Add the following to `Makefile`:

~~~ Makefile
lint:: http-lint

rfc-http-validate ?= rfc-http-validate
.SECONDARY: $(drafts_xml)
.PHONY: http-lint
http-lint: $(addsuffix .http-lint.txt,$(addprefix .,$(drafts)))
.PHONY: .%.http-lint.txt
.%.http-lint.txt: %.xml $(DEPS_FILES)
	$(trace) $< -s http-lint $(rfc-http-validate) -q -m sf.json $<
	@touch $@
~~~
