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


Vratislav Podzimek

Module stats

Total Downloads: 536
Updated: Mar 5, 2024

Installation version

Released on Mar 5, 2024



cfbs add promise-type-http

The http promise type lets you perform HTTP(S) requests from policy.


Here is a simple example of downloading an SVG file (with a HTTP GET request):

bundle agent __main__
      file => "/var/cfengine/cfengine-logo.svg",
      if => not(fileexists("/var/cfengine/cfengine-logo.svg"));


Name Type Description Mandatory Default
url string URL of 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

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

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.


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


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.


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.


  • 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