diff --git a/gaps/gap-34_demand_offer_language_grammar/gap-34_demand_offer_language_grammar.md b/gaps/gap-34_demand_offer_language_grammar/gap-34_demand_offer_language_grammar.md new file mode 100644 index 00000000..5c0d2456 --- /dev/null +++ b/gaps/gap-34_demand_offer_language_grammar/gap-34_demand_offer_language_grammar.md @@ -0,0 +1,29 @@ +--- +gap: GAP-34 +title: Demand/Offer Language Grammar Specifications +description: Grammar Specifications for elements of Demand&Offer language +author: stranger80 +status: Draft +type: Standards +--- + +## Abstract +The Demand&Offer Specification Language [article](https://golem-network.gitbook.io/golem-infrastructure-documentation-develop/architecture/golem-demand-and-offer-specification-language) created as a description for a Golem building block, does only include an informal specification of the language (eg. constraints filter expressions) grammar. An implementation of expression resolver has been created as part of `yagna` reference implementation, however this implementation is not fully consistent, and fails on processing of a number of edge cases. Therefore a formal grammar specification is proposed, with clarifying enhancements, so that a non-ambiguous point of reference exists. + +## Motivation +The proposed grammar fixes a number of errors in the `yagna` reference implementation of the Golem constraint expression resolver, and removes a number of known ambiguities of the original Demand&Offer Specification Language article. + +## Specification +The Demand&Offer constraints expression grammar is specified [here](../../standards/constraints_grammar.md). + +## Rationale +The proposed grammar has been largely based on LDAP Filters [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515). This reference has been consciously selected to avoid "reinventing the wheel" and only modify the existing specification to suit the intended purpose. + +## Backwards Compatibility +The proposed enhancements to the constraint expression language are not 100% backwards compatible, however it is assumed that currently the only working Demand/Offer implementations are the ones maintained by Golem Factory. None of the "breaking" edge cases are used by current Golem Factory-maintained software. + +## Security Considerations +N/A + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). \ No newline at end of file diff --git a/standards/README.md b/standards/README.md index e22e1e28..79cf5f34 100644 --- a/standards/README.md +++ b/standards/README.md @@ -1,6 +1,6 @@ # Golem Computation Resource Standards -## Version 0.7.1 +## Version 0.8.0 This repository defines a framework for the specification of Standards for Computing Resources available on Golem ecosystem. It is supplementary to Golem Demand & Offer Specification Language and is meant to prescriptively implement structure in a broad space of conceivable services. @@ -61,3 +61,6 @@ Properties (and usage conters) marked as `Deprecated` are still supported in the ## Standard properties - Cheat sheet [Cheat sheet](cheat_sheet.md) + +## References +[Demand & Offer Specification Language - Constraints Grammar](./constraints_grammar.md) \ No newline at end of file diff --git a/standards/constraints_grammar.md b/standards/constraints_grammar.md new file mode 100644 index 00000000..f84b974f --- /dev/null +++ b/standards/constraints_grammar.md @@ -0,0 +1,136 @@ +# Demand & Offer Specification Language - Constraints Grammar + +## Demand & Offer Constraint Definition + +The string representation of an LDAP search filter is a string of +UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined +by the following grammar, following the ABNF notation defined [here](https://www.rfc-editor.org/rfc/rfc822). +The filter format uses a prefix notation. + +``` + filter = LPAREN filtercomp RPAREN + filtercomp = and / or / not / item + and = AMPERSAND filterlist + or = VERTBAR filterlist + not = EXCLAMATION filter + filterlist = 1*filter + item = simple / present / substring / extensible + simple = attr filtertype assertionvalue + filtertype = equal / approx / greaterorequal / lessorequal + equal = EQUALS + greater = RANGLE + less = LANGLE + greaterorequal = RANGLE EQUALS + lessorequal = LANGLE EQUALS + present = attr EQUALS ASTERISK + substring = attr EQUALS [initial] any [final] + initial = assertionvalue + any = ASTERISK *(assertionvalue ASTERISK) + final = assertionvalue + assertionvalue = valueencoding + attr = attribute / typedattribute + attribute = attributedescription / attrwithaspect + attrwithaspect = attributedescription LBRACKET aspect RBRACKET + aspect = attributedescription + typedattribute = attribute DOLLAR typecharacter + typecharacter = "v" / "d" / "t" + valueencoding = 0*(normal / escaped) + normal = UTF1SUBSET + escaped = ESC HEX HEX + UTF1SUBSET = + EXCLAMATION = "!" + AMPERSAND = "&" + ASTERISK = "*" + VERTBAR = "|" + EQUALS = "=" + RANGLE = ">" + LANGLE = "<" + RBRACKET = "]" + LBRACKET = "[" + ESC = "\" + DOLLAR = "$" + HEX = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" / "a" / "A" / "b" / "B" / "c" / "C" / "d" / "D" / "e" / "E" / "f" / "F" + +``` + +### `attributedescription` + +The `attributedescription` rule specifies the allowed attribute names. +An attribute name may consist of any Unicode character apart from the following: + +`(`, `)`, `[`, `]`, `=`, `<`, `>`, `\`, `$` + +### `valueencoding` + +The `valueencoding` rule ensures that the entire filter string is a +valid UTF-8 string and provides that the octets that represent the +ASCII characters `*` (ASCII 0x2a), `(` (ASCII 0x28), `)` (ASCII +0x29), `\` (ASCII 0x5c), and `NUL` (ASCII 0x00) are represented as a +backslash `\` (ASCII 0x5c) followed by the two hexadecimal digits +representing the value of the encoded octet. + +This simple escaping mechanism eliminates filter-parsing ambiguities +and allows any filter that can be represented in LDAP to be +represented as a NUL-terminated string. Other octets that are part +of the `normal` set may be escaped using this mechanism, for example, +non-printing ASCII characters. + +For AssertionValues that contain UTF-8 character data, each octet of +the character to be escaped is replaced by a backslash and two hex +digits, which form a single octet in the code of the character. For +example, the filter checking whether the `cn` attribute contained a +value with the character `*` anywhere in it would be represented as +`(cn=*\2a*)`. + + +### AttributeDescription + +An `AttributeDescription` is a string of characters which may include any characters apart of: + + Character + ------------------------------ + = + < + > + ( + ) + [ + ] + $ + \ + + +### Whitespaces + +Any whitespace characters separating constraint expression `filter` elements specified in the grammar above - shall be ignored. This implies, that constraint expression can be freely formatted (eg. indentation, etc), as long as the formatting whitespace is added outside of individual filter expressions (delimited with `()`). + +## Examples + +This section gives a few examples of search filters written using +this notation. + + (cn=Babs Jensen) + (!(cn=Tim Howes)) + (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) + (o=univ*of*mich*) + +The following examples illustrate the use of the escaping mechanism. + + (o=Parens R Us \28for all your parenthetical needs\29) + (cn=*\2A*) + (filename=C:\5cMyFile) + (bin=\00\00\00\04) + (sn=Lu\c4\8di\c4\87) + +The first example shows the use of the escaping mechanism to +represent parenthesis characters. The second shows how to represent a +"*" in a value, preventing it from being interpreted as a substring +indicator. The third illustrates the escaping of the backslash +character. + +The fourth example shows a filter searching for the four-byte value +0x00000004, illustrating the use of the escaping mechanism to +represent arbitrary data, including NUL characters. + +The final example illustrates the use of the escaping mechanism to +represent various non-ASCII UTF-8 characters.