From 32e5f1eb7a0862876e2ada4ee8ee72bec8afede5 Mon Sep 17 00:00:00 2001
From: "Mark A. Grondona" <mark.grondona@gmail.com>
Date: Tue, 1 Mar 2022 13:59:11 -0800
Subject: [PATCH] rfc31: add RFC 31: Job Constraints Specification

Problem: There is no defintion of how to encode job constraints in
a standardized format.

Introduce RFC 31: Job Constraints Specification, which includes a simple,
but extensible format for encoding job constraints, inspired by the
json-logic definition at https://jsonlogic.com.
---
 README.md   |   1 +
 index.rst   |   1 +
 spec_31.rst | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 127 insertions(+)
 create mode 100644 spec_31.rst

diff --git a/README.md b/README.md
index 62041c7e..c82ea262 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,7 @@ Table of Contents
 - [28/Flux Resource Acquisition Protocol Version 1](spec_28.rst)
 - [29/Hostlist Format](spec_29.rst)
 - [30/Job Urgency](spec_30.rst)
+- [31/Job Constraints Specification](spec_31.rst)
 
 Build Instructions
 ------------------
diff --git a/index.rst b/index.rst
index 39dcd7e1..77b50cdb 100644
--- a/index.rst
+++ b/index.rst
@@ -249,3 +249,4 @@ This specification describes the Flux job urgency parameter.
    spec_28
    spec_29
    spec_30
+   spec_31
diff --git a/spec_31.rst b/spec_31.rst
new file mode 100644
index 00000000..06a3fa02
--- /dev/null
+++ b/spec_31.rst
@@ -0,0 +1,125 @@
+.. github display
+   GitHub is NOT the preferred viewer for this file. Please visit
+   https://flux-framework.rtfd.io/projects/flux-rfc/en/latest/spec_26.html
+
+31/Job Constraints Specification
+================================
+
+This specification describes an extensible format for the description of
+job constraints.
+
+-  Name: github.com/flux-framework/rfc/spec_26.rst
+-  Editor: Mark A. Grondona <mgrondona@llnl.gov>
+-  State: raw
+
+Language
+--------
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to
+be interpreted as described in `RFC 2119 <https://tools.ietf.org/html/rfc2119>`__.
+
+Related Standards
+-----------------
+
+-  :doc:`14/Canonical Job Specification <spec_14>`
+-  :doc:`20/Resource Set Specification Version 1 <spec_20>`
+
+Goals
+-----
+
+-  Define a format for the specification of general constraints in jobspec
+-  Embed extensibility into the format to allow for growth of feature set
+
+Background
+----------
+
+It is common practice for resource management systems to allow job
+requests to contain constraints beyond the size and count of resources
+that are being requested. Most often, these constraints specify a set
+of allowable features or *properties* which the assigned resources must
+satisfy. However more complex constraint satisfaction problems are often
+supported to allow for advanced resource matching.
+
+This RFC defines an extensible format for the specification of job
+constraints in JSON.
+
+Representation
+--------------
+
+Job constraints SHALL be represented as a JSON object, which loosely
+follows the `JsonLogic <https://jsonlogic.com/>`_ format of
+
+.. code:: json
+
+  { "operator": [ "values", ] }
+
+where each ``value`` can also be a constraint object. This format has
+several advantages:
+
+ * The set of supported operators can be restricted for ease of implementation
+   then later extended for additional functionality
+ * The format allows nesting to support complex constraints
+ * Simple cases can be expressed simply
+
+In this version of the RFC, only the following constraint operators SHALL be
+supported
+
+ - ``properties``: The set of values SHALL designate a set of required
+   properties on execution targets. As a special case, if a property value
+   begins with the character ``^``, then the remaining part of the value
+   SHALL indicate a property that MUST NOT be included in the allocated
+   resource set.
+
+The following constraint operators MAY be supported. If a job is submitted
+using these constraint operators, and the operators are not supported by
+the instance, then the job SHALL be rejected with an appropriate error
+message:
+
+ - ``not``: Logical negation. Takes a single value and negates it. For
+   example, to constrain a job to only those resources that do not have
+   a set of attributes ``foo`` and ``bar``, the following expression could
+   be used
+
+   .. code:: json
+
+      { "not": [{ "properties": [ "foo", "bar" ]}] }
+
+ - ``or``: Simple logical ``or``. Evaluates true if any one of the ``value``
+   arguments is true, e.g. to constrain jobs to resources that have either
+   ``foo`` *or* ``bar``:
+
+   .. code:: json
+
+      { "or": [{ "properties": [ "foo" ]}, { "properties": [ "bar" ]}] }
+
+   
+ - ``and``: Simple logical ``and``. Evaluates to true only if all ``value``
+   arguments are true, e.g.
+
+   .. code:: json
+
+      { "and":
+        [ {"properties": [ "a" ] },
+          { "not": [{ "properties": [ "foo", "bar" ]}
+        ]
+      }
+     
+
+Examples
+--------
+
+Constrain resources such that all execution targets have property ``ssd``:
+
+.. code:: json
+
+  { "properties": [ "ssd" ] }
+
+Constrain resources such that no execution targets with property ``slowgpu``
+are allocated:
+
+.. code:: json
+
+  { "properties": [ "^slowgpu" ] }
+
+