promise-type-http

Promise type to perform HTTP(S) requests from policy

Maintainer

Vratislav Podzimek

Module stats

Total Downloads: 376
Updated: Nov 3, 2021

Installation version

Version
Released on Nov 3, 2021

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"

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 [4/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-Lenght 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