Define request and response objects

[ghost]

BACKGROUND

You may recall that #168 was originally filed to define a "web request" object to capture the headers from web requests. This is useful for web analysis tools. Ultimately, I proposed a design that I thought would avoid the need for a new object. I proposed to add an immutableState property to the threadFlow object. Please see §3.34.5, "threadFlowLocation.immutableState property", for an example. This proposal was approved in e-ballot-3.

What I missed was that not every analysis rule in a web analysis tool uses code flows! We need a place to put the headers that does not rely on result.codeFlows being present. Furthermore, we really need more than just the headers. I'm writing a SARIF converter now for a web analyzer whose native output format includes not only the headers, but the request URL (well, that fits naturally as result.location), the method (e.g., POST), and the body.

So we really do need a full-fledged request object (and a response object) to capture what web analyzers emit.

We will use the same caching and externalization mechanisms that we used for addresses and logical locations, to avoid duplicating information when a single request produces multiple issues, and to reduce file size.

PROPOSAL

• Define a request object with the following properties:

  • index of type integer, optional: an index into run.requests (see below)
  • protocol of type string, optional. Example: "HTTP"
  • version of type string, optional. Example: "1.1"
  • target of type string, optional. Example: "/tools/CodeScanner"
  • method of type string, optional, with well-known values GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE, CONNECT.
  • headers of type object with string-valued properties, optional.
  • parameters of type object with string-valued properties, optional.
  • body of type artifactContent, optional.

• Define a response object with the following properties:

  • index of type integer, optional: an index into run.responses (see below).
  • protocol of type string, optional. Example: "HTTP"
  • version of type string, optional. Example: "1.1"
  • statusCode of type integer, optional. Example: 404
  • reasonPhrase of type string, optional. Example: Not found
  • headers of type object with string-valued properties, optional.
  • body of type artifactContent, optional.

• In the result object:

  • Add a property request of type request, optional.
  • Add a property response of type response, optional.

• In the threadFlowLocation object:

  • Add a property request of type request, optional.
  • Add a property response of type response, optional.

• In the run object:

  • Add a property requests of type request[], optional, unique, minItems: 0, default: [].
  • Add a property responses of type response[], optional, unique, minItems, 0, default: [].

• In the object held by run.externalPropertyFileReferences (this object does not have a name):

  • Add a property requests of type externalPropertyFileReference[], optional, unique, minItems: 0, default: [].
  • Add a property responses of type externalPropertyFileReference[], optional, unique, minItems: 0, default: [].

• In the externalProperties object:

  • Add a property requests of type request[], optional, unique, minItems: 0, default: []
  • Add a property responses of type response[], optional, unique, minItems: 0, default: []