From eea3dfa969161fce83644f98bd26603b2cb44e7c Mon Sep 17 00:00:00 2001 From: Matthias Ahouansou Date: Wed, 1 May 2024 09:48:11 +0000 Subject: [PATCH 1/4] Mention notifying AS for sender_localpart events (#1810) Signed-off-by: Matthias Ahouansou --- .../newsfragments/1810.clarification | 1 + .../application-service/definitions/registration.yaml | 11 +++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1810.clarification diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification new file mode 100644 index 000000000..66dab4954 --- /dev/null +++ b/changelogs/application_service/newsfragments/1810.clarification @@ -0,0 +1 @@ +Clarify that appservices should be notified of events relating to the sender_localpart user. diff --git a/data/api/application-service/definitions/registration.yaml b/data/api/application-service/definitions/registration.yaml index d9dfe7484..2d65a32c1 100644 --- a/data/api/application-service/definitions/registration.yaml +++ b/data/api/application-service/definitions/registration.yaml @@ -29,7 +29,9 @@ properties: description: A secret token that the homeserver will use authenticate requests to the application service. sender_localpart: type: string - description: The localpart of the user associated with the application service. + description: |- + The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or + is a joined member of the room where the event occurred. namespaces: type: object title: Namespaces @@ -40,9 +42,10 @@ properties: - $ref: namespace_list.yaml - description: |- A list of namespaces defining the user IDs that the application - service is interested in. Events will be sent to the AS if a - local user matching one of the namespaces is the target of the event, - or is a joined member of the room where the event occurred. + service is interested in, in addition to its `sender_localpart`. + Events will be sent to the AS if a local user matching one of the + namespaces is the target of the event, or is a joined member of + the room where the event occurred. rooms: allOf: - $ref: namespace_list.yaml From 48f4c4954fb7445fc9a64cf9201213e54534d802 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 2 May 2024 11:10:16 +0100 Subject: [PATCH 2/4] Include information about additionalProperties in object tables (#1798) Currently, if we have an object which has additionalProperties in addition to properties, that information gets lost. This PR seeks to address that. --- .../internal/newsfragments/1798.clarification | 1 + data/api/identity/v2_terms.yaml | 1 - .../json-schema/resolve-additional-types.html | 45 +++++++++++++------ .../partials/openapi/render-object-table.html | 40 ++++++++++++++--- 4 files changed, 67 insertions(+), 20 deletions(-) create mode 100644 changelogs/internal/newsfragments/1798.clarification diff --git a/changelogs/internal/newsfragments/1798.clarification b/changelogs/internal/newsfragments/1798.clarification new file mode 100644 index 000000000..5bd28a93c --- /dev/null +++ b/changelogs/internal/newsfragments/1798.clarification @@ -0,0 +1 @@ +Show information about "Additional Properties" in object tables. diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index d9eea90e2..d7c231d4b 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -52,7 +52,6 @@ paths: might be and could be "alpha", semantically versioned, or arbitrary. required: - version - # TODO: TravisR - Make this render additionalProperties: type: object title: Internationalised Policy diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index cf5e99534..f6f096462 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -29,6 +29,8 @@ * * * title * * properties + * * additionalProperties + * * patternProperties * * required * * enum * * anchor @@ -45,27 +47,31 @@ "schema" .schema "anchor_base" .anchor_base "name" (.name | default .schema.title | default "") + "top_level" true ) }} {{ return $res.objects }} /* * A helper for the resolve-additional-types partial. * - * Takes the same inputs as resolve-additional-types itself, except that `name` is mandatory. + * Takes the same inputs as resolve-additional-types itself, except: + * * `name` is mandatory. + * * `top_level`, if set, indicates that this is the top-level object. * * Returns a dict containing: * * * `objects`: The array of object schema definitions. * - * * `schema`: An updated copy of the `schema` input (eg, nested `allOf` - * entries are expanded, and an `anchor` may be added). If the input - * `schema` was itself an object, this will be the same as the first entry - * in `objects`. + * * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added). + * If the input `schema` was itself an object that we should create a table for, + * this will be the same as the first entry in `objects`. */ {{ define "partials/resolve-additional-types-inner" }} {{ $this_object := .schema }} {{ $anchor_base := .anchor_base }} {{ $name := .name }} + {{ $top_level := .top_level }} + {{ $all_objects := slice }} {{ if eq $this_object.type "object" }} @@ -126,12 +132,24 @@ {{ $this_object = merge $this_object (dict "properties" $updated_properties) }} {{ end }} - /* Finally, prepend the updated schema for the top-level object onto the $all_objects array */ - {{ $tmp := slice $this_object }} - {{ if $all_objects }} - {{ $tmp = $tmp | append $all_objects }} + /* We'll want to create a table for `$this_object` itself if either: + * + * - The object has some regular properties (not just patternProperties or additionalProperties), or: + * - It is the top-level object. (We use a special format of table for top-level objects that + * only have patternProperties or additionalProperties) + * + * In those cases, prepend the updated schema for the top-level object onto the $all_objects array. + * + * We think about this last so that we can take advantage of any updates to the schema that happened + * above (in particular, addition of `anchor` attributes). + */ + {{ if or $this_object.properties $top_level }} + {{ $tmp := slice $this_object }} + {{ if $all_objects }} + {{ $tmp = $tmp | append $all_objects }} + {{ end }} + {{ $all_objects = $tmp }} {{ end }} - {{ $all_objects = $tmp }} {{ end }} {{ if eq $this_object.type "array" }} @@ -198,8 +216,7 @@ * * Returns a dict containing: * * `objects`: The array of object schema definitions. - * * `schema`: An updated copy of the `schema` input (eg, nested `allOf` - * entries are expanded, and an `anchor` may be added). + * * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added). */ {{ define "partials/get-additional-objects" }} /* .name is the name of the object for logging purposes */ @@ -211,7 +228,7 @@ {{ errorf "Invalid call to partials/get-additional-objects: %s is not a map" $name .this_object }} {{ end }} - {{ $res := partial "resolve-additional-types-inner" (dict "schema" .this_object "anchor_base" .anchor_base "name" $name) }} + {{ $res := partial "resolve-additional-types-inner" (dict "schema" .this_object "anchor_base" .anchor_base "name" $name "top_level" false) }} {{ range $res.objects }} {{ $all_objects = $all_objects | append (partial "clean-object" .) }} {{ end }} @@ -226,5 +243,5 @@ * but with (for example) different examples will be considered different. */ {{ define "partials/clean-object" }} - {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }} + {{ return (dict "title" .title "properties" .properties "additionalProperties" .additionalProperties "patternProperties" .patternProperties "required" .required "enum" .enum "anchor" .anchor) }} {{ end }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 21d77c89e..72ea5a8ae 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -9,11 +9,11 @@ * `properties`: optional dictionary of the properties to list, each given as: `property_name` : `property_data` - * `additionalProperties`: optional dictionary for properties with undefined - names, in the same format as `property_data` + * `additionalProperties`: a JSON Schema for additional properties on the + object. * `patternProperties`: optional dictionary for properties with names adhering - to a regex pattern, in the same format as `property_data` + to a regex pattern. A map from regex pattern to JSON Schema. * `required`: optional array containing the names of required properties. In some cases (such as response body specifications) this isn't used, and @@ -26,7 +26,6 @@ {{ $required := .required}} {{ if $properties }} - {{ with $title }} {{ . }} @@ -52,9 +51,40 @@ {{ end }} + {{/* + If the object has additional properties *as well as* regular properties, we add a special row to the table. + + Note that, per https://json-schema.org/draft/2020-12/json-schema-core#name-boolean-json-schemas, JSON schemas + can be a simple "true" or "false" as well as the more normal object. + + `additionalProperties: true` is pretty much the default for Matrix (it means: "you're allowed to include random + unspecced properties in your object"), so nothing to do here. + + `additionalProperties: false` means "you're not allowed to include any unspecced properties in your object". We + may want to consider how to display that; for now we just ignore it. + + TODO: support `patternProperties` here. + */}} + {{ if reflect.IsMap .additionalProperties }} + + + <Other properties> + {{ partial "partials/property-type" .additionalProperties | safeHTML }} + {{ partial "partials/property-description" (dict "property" .additionalProperties) }} + + {{ end }} {{ else if (or .additionalProperties .patternProperties) }} + +{{/* +A special format of table for objects which only have additionalProperties or patternProperties. + +This is only ever used for top-level objects. Nested objects in this situation are just shown +as rows within their parent object, and don't get their own table. (They are filtered out in +resolve-additional-types.) +*/}} + {{ with $title }} {{ . }} @@ -116,7 +146,7 @@ {{ else if or (reflect.IsSlice .type) .oneOf }} {{/* It's legal to specify an array of types. - + There are two ways to do that: - Use an array of strings. - Use oneOf, with items having a schema. From 98d85cf421f23233bbfde4232d78634836281cae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 8 May 2024 02:50:36 +0200 Subject: [PATCH 3/4] Add support for rendering string formats (#1814) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1814.clarification | 1 + data/custom-formats.yaml | 5 +++ .../partials/openapi/render-object-table.html | 32 +++++++++++++++++-- 3 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 changelogs/internal/newsfragments/1814.clarification diff --git a/changelogs/internal/newsfragments/1814.clarification b/changelogs/internal/newsfragments/1814.clarification new file mode 100644 index 000000000..a540ea7e0 --- /dev/null +++ b/changelogs/internal/newsfragments/1814.clarification @@ -0,0 +1 @@ +Add support for rendering string formats. diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml index f0001c80d..5da7e6abb 100644 --- a/data/custom-formats.yaml +++ b/data/custom-formats.yaml @@ -31,3 +31,8 @@ mx-event-id: title: Event ID url: /appendices#event-ids # regex: "^\\$" + +uri: + title: URI + url: http://tools.ietf.org/html/rfc3986 + # no regex diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 72ea5a8ae..d2b09acb6 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -128,6 +128,8 @@ * `anchor`: optional HTML element id for the target type, which will be used to link to it. + * `format`: optional string for the format of the type, used for strings. + */}} {{ define "partials/property-type" }} {{ $type := "" }} @@ -143,6 +145,15 @@ {{ $items := .items }} {{ $inner_type := partial "property-type" $items }} {{ $type = delimit (slice "[" $inner_type "]") "" }} + {{ else if eq .type "string" }} + {{ $type = "string" }} + + {{/* If the string uses a known format, use it. */}} + {{ with .format }} + {{ with partial "custom-format" . }} + {{ $type = . }} + {{ end }} + {{ end }} {{ else if or (reflect.IsSlice .type) .oneOf }} {{/* It's legal to specify an array of types. @@ -167,7 +178,7 @@ {{ $type = delimit $types "|" }} {{ else }} - {{/* A simple type like string or boolean */}} + {{/* A simple type like integer or boolean */}} {{ $type = (htmlEscape .type) }} {{ end }} @@ -241,8 +252,8 @@ {{ range $formatId, $formatType := $formatMap.Values }} {{ $formatKey := "string" }} {{ if ne $formatId "string" }} - {{ with index site.Data "custom-formats" $formatId }} - {{ $formatKey = printf "%s" (htmlEscape .url) (htmlEscape .title) }} + {{ with partial "custom-format" $formatId }} + {{ $formatKey = . }} {{ else }} {{ errorf "Unsupported value for `x-pattern-format`: %s" $formatId }} {{ end }} @@ -290,3 +301,18 @@ {{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}} {{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}} {{ end }} + + +{{/* + Computes the type to display for a string format, given the identifier of + the format as a string. +*/}} +{{ define "partials/custom-format" }} + {{ $customFormat := "" }} + + {{ with index site.Data "custom-formats" . }} + {{ $customFormat = printf "%s" (htmlEscape .url) (htmlEscape .title) }} + {{ end }} + + {{ return $customFormat }} +{{ end }} From f4b34ba962b28a9372090759a74ca587b4774a9b Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 8 May 2024 13:22:26 +0100 Subject: [PATCH 4/4] Note that whitespace around `Authorization` param commas is allowed (#1818) --- .../server_server/newsfragments/1818.clarification | 1 + content/server-server-api.md | 12 +++++++----- 2 files changed, 8 insertions(+), 5 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1818.clarification diff --git a/changelogs/server_server/newsfragments/1818.clarification b/changelogs/server_server/newsfragments/1818.clarification new file mode 100644 index 000000000..8c50b6ace --- /dev/null +++ b/changelogs/server_server/newsfragments/1818.clarification @@ -0,0 +1 @@ +Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index fb1b06f4e..e92d871c5 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -350,9 +350,10 @@ def authorization_headers(origin_name, origin_signing_key, The format of the Authorization header is given in [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In -summary, the header begins with authorization scheme `X-Matrix`, followed by -one or more spaces, followed by a comma-separated list of parameters written as -name=value pairs. The names are case insensitive and order does not matter. The +summary, the header begins with authorization scheme `X-Matrix`, followed by one +or more spaces, followed by a comma-separated list of parameters written as +name=value pairs. Zero or more spaces and tabs around each comma are allowed. +The names are case insensitive and order does not matter. The values must be enclosed in quotes if they contain characters that are not allowed in `token`s, as defined in [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a @@ -363,8 +364,9 @@ replaced by the character that follows the backslash. For compatibility with older servers, the sender should - only include one space after `X-Matrix`, -- only use lower-case names, and -- avoid using backslashes in parameter values. +- only use lower-case names, +- avoid using backslashes in parameter values, and +- avoid including whitespace around the commas between name=value pairs. For compatibility with older servers, the recipient should allow colons to be included in values without requiring the value to be enclosed in quotes.