promise-type-http

Promise type to perform HTTP(S) requests from policy.

Maintainer

Vratislav Podzimek

Module stats

Total Downloads: 530
Updated: Oct 12, 2022

Installation version

Version
Released on Oct 12, 2022

Tags

Installation

                    
cfbs add promise-type-http
Description
Dependencies
Comments

http promise type

Synopsis

  • Name: http
  • Version: 1.0.0
  • Description: Perform HTTP(S) requests from policy.

Promiser and attributes

The promiser can either be a URL of the request or, if the url attribute is used (see below), it can be an arbitrary string. All attributes are optional if the URL is specified in the promiser.

Attributes

Name Type Description Mandatory Default
url string URL or the request (starting with "http://" or "https://") No promiser
file string File system path for where to save the response (body). No -
method string HTTP method of the request (GET, POST, PUT, DELETE or PATCH) No -
headers string, slist or data headers to send with the request (data with key-value pairs, slist with colon-separated key-value pairs, or string with key:value pairs) on separate lines No -
payload string or data data payload to send with the request (string or data that will be converted to a string); @\/some\/path values can be used to send file-based payloads No -
insecure string Whether to skip TLS validation of the server's certificate ("true") or not ("false") No "false"

Note: if no file attribute is provided the request will be sent to /dev/null. This is useful for something like a REST API endpoint where all you care about is an OK response (http code between 200 and 300) that results in the promise being KEPT

Result classes

On success, each http promise defines a class that is in the form of $(this.promiser)_METHOD_request_done. On failure, class of form $(this.promiser)_METHOD_request_failed is defined plus classes of form:

  • $(this.promiser)_METHOD_payload_failed (payload-related failures)
  • $(this.promiser)_METHOD_payload_file_failed (file-based payload failures)
  • $(this.promiser)_METHOD_payload_conversion_failed (payload conversion failures)
  • $(this.promiser)_METHOD_file_failed (file-related failures, see above)

in the respective cases. There are currently no special classes for HTTP response codes, only the $(this.promiser)_METHOD_request_failed class is defined in case the response code is not an OK code.

The promiser is canonified in all the above classes.

Examples

bundle agent __main__
{
  http:
    "https://cfengine.com/images/cfengine-logo.svg"
      file => "/var/cfengine/cfengine-logo.svg",
      if => not(fileexists("/var/cfengine/cfengine-logo.svg"));
}

Authors

This software was created by the team at Northern.tech AS, with many contributions from the community. Thanks everyone!

CFEngine is sponsored by Northern.tech AS

Contribute

Feel free to open pull requests to expand this documentation, add features or fix problems. You can also pick up an existing task or file an issue in our bug tracker.

License

This software is licensed under the MIT License. See LICENSE in the root of the repository for the full license text.

Drawbacks and TODOs

The current implementation of the module is not idempotent and so a request is made every time a promise of the http promise type is evaluated. Result classes can be used to ensure the request is only made once.

TODO TODO [6/8]

  • insecure attribute
  • payload of type data should result in the Content-Type: application/json added to headers
  • @/some/file/path special values for POST/PUT requests
  • result classes to allow idempotency without locking
  • progress reporting if response Content-Length is big
  • GET requests should not overwrite data if it is the same
  • checksum attribute
  • result classes for 4xx, 5xx,… failure response codes
comments powered by Disqus