General concepts¶
Exchanges¶
HTTPolice takes HTTP exchanges (also known as transactions) as input. Every exchange can consist of 1 request and 1+ responses. Usually there is just 1 response, but sometimes there are interim (1xx) responses before the main one.
If you only want to check the request, you can omit responses from the exchange.
On the other hand, if you only want to check the responses, you should still provide the request (if possible), because responses cannot be properly analyzed without it. If you really have no access to the request, you can omit it, but many checks will be disabled.
Reports¶
The output of HTTPolice is a report containing notices.
Every notice has an ID (such as “1061”) that can be used to silence it, and one of three severities:
- error
Something is clearly wrong. For example, a “MUST” requirement of a standard is clearly violated.
Please note that not all errors may be actual problems. Sometimes there is a good reason to violate a standard. Sometimes you just don’t care. You decide which errors to fix and which to ignore. If you don’t want to see an error, you can silence it.
- comment
- Something is possibly wrong or sub-optimal, but HTTPolice isn’t sure. For example, a “SHOULD” requirement of a standard is clearly violated.
- debug
- This just explains why HTTPolice did (or did not do) something. For example, when HTTPolice thinks that a response was served from cache, it will report a debug notice to explain why it thinks so. This may help you understand further cache-related notices for that response.
Silencing unwanted notices¶
You can silence notices that you don’t want to see. They will disappear from reports and from the Python API.
Please note that some notice IDs can stand for a range of problems. For example, most errors in header syntax are reported as notice 1000, so if you silence it, you lose a big chunk of HTTPolice’s functionality.
Silencing globally¶
When using the httpolice
command-line tool,
you can use the -s
option to specify notice IDs to silence:
$ httpolice -s 1089 -s 1194 ...
Integration methods have similar mechanisms.
For example, mitmproxy integration understands the same -s
option.
Silencing locally¶
You can also silence notices on individual messages
by adding the special HTTPolice-Silence
header to them.
Its value is a comma-separated list of notice IDs. For example:
HTTP/1.1 405 Method Not Allowed
Content-Length: 0
HTTPolice-Silence: 1089, 1110
Requests can also silence notices on responses (but not vice-versa)
by adding a resp
keyword after an ID:
GET /index.html HTTP/1.1
User-Agent: Mozilla/5.0
HTTPolice-Silence: 1033 resp, 1031