From c9c433bc15ede21a806900503df5d9a935984faa Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Mon, 30 Nov 2015 14:31:24 +0000 Subject: [PATCH 01/33] Make section depths consistent --- specification/intro.rst | 26 +++++++++++++------------- specification/targets.yaml | 8 ++++---- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/specification/intro.rst b/specification/intro.rst index 8c08bf24..211a3562 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -9,7 +9,7 @@ https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of revision ``{{git_version}}`` - https://github.com/matrix-org/matrix-doc/tree/{{git_rev}} APIs -~~~~ +---- The following APIs are documented in this specification: - `Client-Server API `_ for writing Matrix clients. @@ -19,7 +19,7 @@ The following APIs are documented in this specification: There are also some `appendices `_. Changelog -~~~~~~~~~ +--------- {{spec_changelog}} For a full changelog, see @@ -29,7 +29,7 @@ https://github.com/matrix-org/matrix-doc/blob/master/CHANGELOG.rst .. sectnum:: Introduction -============ +------------ .. WARNING:: The Matrix specification is still evolving: the APIs are not yet frozen and this document is in places a work in progress or stale. We have made every @@ -103,10 +103,10 @@ reliably and persistently pushed from A to B in an inter-operable and federated manner. Overview -======== +-------- Architecture ------------- +~~~~~~~~~~~~ Matrix defines APIs for synchronising extensible JSON objects known as "events" between compatible clients, servers and services. Clients are @@ -158,7 +158,7 @@ a long-lived GET request. Users -~~~~~ ++++++ Each client is associated with a user account, which is identified in Matrix using a unique "User ID". This ID is namespaced to the homeserver which @@ -173,7 +173,7 @@ this user. The ``domain`` of a user ID is the domain of the homeserver. - Need to specify precise grammar for Matrix IDs Events -~~~~~~ +++++++ All data exchanged over Matrix is expressed as an "event". Typically each client action (e.g. sending a message) correlates with exactly one event. Each event @@ -188,7 +188,7 @@ of a "Room". .. _package naming conventions: https://en.wikipedia.org/wiki/Java_package#Package_naming_conventions Event Graphs -~~~~~~~~~~~~ +++++++++++++ .. _sect:event-graph: @@ -212,7 +212,7 @@ of its parents. The root event should have a depth of 1. Thus if one event is before another, then it must have a strictly smaller depth. Room structure -~~~~~~~~~~~~~~ +++++++++++++++ A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will @@ -291,7 +291,7 @@ from the other servers participating in a room. Room Aliases -++++++++++++ +^^^^^^^^^^^^ Each room can also have multiple "Room Aliases", which look like:: @@ -327,7 +327,7 @@ that are in the room that can be used to join via. |________________________________| Identity -~~~~~~~~ +++++++++ Users in Matrix are identified via their matrix user ID (MXID). However, existing 3rd party ID namespaces can also be used in order to identify Matrix @@ -347,7 +347,7 @@ user IDs using 3PIDs. Profiles -~~~~~~~~ +++++++++ Users may publish arbitrary key/value data associated with their account - such as a human readable display name, a profile photo URL, contact information @@ -358,7 +358,7 @@ as a human readable display name, a profile photo URL, contact information names allowed to be? Private User Data -~~~~~~~~~~~~~~~~~ ++++++++++++++++++ Users may also store arbitrary private key/value data in their account - such as client preferences, or server configuration settings which lack any other diff --git a/specification/targets.yaml b/specification/targets.yaml index cdbfa62e..310870a0 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -7,9 +7,9 @@ targets: - client_server_api.rst - { 1: events.rst } - { 1: event_signing.rst } - - modules.rst - - { 1: feature_profiles.rst } - - { 1: "group:modules" } # reference a group of files + - { 1: modules.rst } + - { 2: feature_profiles.rst } + - { 2: "group:modules" } # reference a group of files application_service: files: - application_service_api.rst @@ -37,7 +37,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/account_data.rst -title_styles: ["=", "-", "~", "+", "^", "`"] +title_styles: ["=", "-", "~", "+", "^", "`", "@"] # The templating system doesn't know the right title style to use when generating # RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title From ebed3b60bd68ef8a258ec9ebbd866477283297c9 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 15:58:15 +0000 Subject: [PATCH 02/33] Add trailing slashes to links --- scripts/speculator/main.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/speculator/main.go b/scripts/speculator/main.go index 602cdb57..1c2780e3 100644 --- a/scripts/speculator/main.go +++ b/scripts/speculator/main.go @@ -469,12 +469,12 @@ func listPulls(w http.ResponseWriter, req *http.Request) { } s := "
    " for _, pull := range pulls { - s += fmt.Sprintf(`
  • %d: %s: %s: spec spec diff rst diff
    • `, + s += fmt.Sprintf(`
  • %d: %s: %s: spec spec diff rst diff
    • `, pull.Number, pull.User.HTMLURL, pull.User.Login, pull.HTMLURL, pull.Title, pull.Number, pull.Number, pull.Number) } - s += `
View the spec at head
` + s += `
View the spec at head
` if *includesDir != "" { - s += `
View the spec at head styled like matrix.org
` + s += `
View the spec at head styled like matrix.org
` } io.WriteString(w, s) From 681c25820602b543264eb81f341284f6d4671ab8 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 16:56:28 +0000 Subject: [PATCH 03/33] Fix turnServer endpoint --- api/client-server/voip.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/voip.yaml b/api/client-server/voip.yaml index 5fdf1ca7..629f2c17 100644 --- a/api/client-server/voip.yaml +++ b/api/client-server/voip.yaml @@ -18,7 +18,7 @@ securityDefinitions: name: access_token in: query paths: - "/turnServer": + "/voip/turnServer": get: summary: Obtain TURN server credentials. description: |- From f6229f649a88a2ec365f270896d9917ab6e86244 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 16:58:40 +0000 Subject: [PATCH 04/33] Remove confusing wording --- .../modules/typing_notifications.rst | 22 ------------------- 1 file changed, 22 deletions(-) diff --git a/specification/modules/typing_notifications.rst b/specification/modules/typing_notifications.rst index da383e73..8be1ac28 100644 --- a/specification/modules/typing_notifications.rst +++ b/specification/modules/typing_notifications.rst @@ -34,28 +34,6 @@ to inform the server that the user has stopped typing. {{typing_http_api}} -Server behaviour ----------------- - -Servers MUST emit typing EDUs in a different form to ``m.typing`` events which -are shown to clients. This form looks like:: - - { - "type": "m.typing", - "content": { - "room_id": "!room-id-here:matrix.org", - "user_id": "@user-id-here:matrix.org", - "typing": true/false - } - } - -This does not contain timing information so it is up to originating homeservers -to ensure they eventually send "stop" notifications. - -.. TODO - ((This will eventually need addressing, as part of the wider typing/presence - timer addition work)) - Security considerations ----------------------- From 97fd1fdd627c45522cf888ec5d858c067933b02c Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 17:02:23 +0000 Subject: [PATCH 05/33] Embed client and server release numbers Note that this also removes the changelog - I'm going to re-add the changelog differently soon. --- scripts/gendoc.py | 35 +++++++++++++++++++++---- scripts/generate-http-docs.sh | 13 ++++++++- specification/intro.rst | 20 ++++---------- templating/build.py | 22 ++++++++++++++-- templating/matrix_templates/sections.py | 4 --- templating/matrix_templates/units.py | 21 +++++---------- 6 files changed, 73 insertions(+), 42 deletions(-) diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 9b87cb30..801c06bb 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -250,7 +250,7 @@ def addAnchors(path): f.write(line + "\n") -def run_through_template(input, set_verbose): +def run_through_template(input, set_verbose, substitutions): tmpfile = './tmp/output' try: with open(tmpfile, 'w') as out: @@ -260,6 +260,9 @@ def run_through_template(input, set_verbose): "-o", "../scripts/tmp", "../scripts/"+input ] + for k, v in substitutions.items(): + args.append("--substitution=%s=%s" % (k, v)) + if set_verbose: args.insert(2, "-v") log("EXEC: %s" % " ".join(args)) @@ -392,7 +395,7 @@ def cleanup_env(): shutil.rmtree("./tmp") -def main(requested_target_name, keep_intermediates): +def main(requested_target_name, keep_intermediates, substitutions): prepare_env() log("Building spec [target=%s]" % requested_target_name) @@ -407,7 +410,7 @@ def main(requested_target_name, keep_intermediates): target = get_build_target("../specification/targets.yaml", target_name) build_spec(target=target, out_filename=templated_file) - run_through_template(templated_file, VERBOSE) + run_through_template(templated_file, VERBOSE, substitutions) fix_relative_titles( target=target, filename=templated_file, out_filename=rst_file, @@ -417,13 +420,21 @@ def main(requested_target_name, keep_intermediates): if requested_target_name == "all": shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst") - run_through_template("tmp/howto.rst", False) # too spammy to mark -v on this + run_through_template("tmp/howto.rst", False, substitutions) # too spammy to mark -v on this rst2html("tmp/howto.rst", "gen/howtos.html") if not keep_intermediates: cleanup_env() +def extract_major(s): + major_version = s + match = re.match("^(r\d)+(\.\d+)?$", s) + if match: + major_version = match.group(1) + return major_version + + if __name__ == '__main__': parser = ArgumentParser( "gendoc.py - Generate the Matrix specification as HTML to the gen/ folder." @@ -441,9 +452,23 @@ if __name__ == '__main__': "--verbose", "-v", action="store_true", help="Turn on verbose mode." ) + parser.add_argument( + "--client_release", "-c", action="store", default="unstable", + help="The client-server release tag to generate, e.g. r1.2" + ) + parser.add_argument( + "--server_release", "-s", action="store", default="unstable", + help="The server-server release tag to generate, e.g. r1.2" + ) args = parser.parse_args() if not args.target: parser.print_help() sys.exit(1) VERBOSE = args.verbose - main(args.target, args.nodelete) + substitutions = { + "%CLIENT_RELEASE_LABEL%": args.client_release, + "%CLIENT_MAJOR_VERSION%": extract_major(args.client_release), + "%SERVER_RELEASE_LABEL%": args.server_release, + "%SERVER_MAJOR_VERSION%": extract_major(args.server_release), + } + main(args.target, args.nodelete, substitutions) diff --git a/scripts/generate-http-docs.sh b/scripts/generate-http-docs.sh index b3894a2c..48c01bdb 100755 --- a/scripts/generate-http-docs.sh +++ b/scripts/generate-http-docs.sh @@ -4,6 +4,17 @@ # It takes all of the swagger YAML files for the client-server API, and turns # them into API docs, with none of the narrative found in the rst files which # normally wrap these API docs. +# +# Optionally takes one positional argument, the label of the release, e.g. r1.2. +# This falls back to "unstable" if unspecified. + +if [[ $# == 1 ]]; then + client_release=$1 +else + client_release="unstable" +fi + +client_major_version="$(echo "${client_release}" | perl -pe 's/^(r\d+)\..*$/$1/g')" cd "$(dirname $0)" @@ -23,5 +34,5 @@ for f in ../api/client-server/*.yaml; do echo "{{${f/-/_}}}" >> tmp/http_apis done -(cd ../templating ; python build.py -i matrix_templates -o ../scripts/gen ../scripts/tmp/http_apis) +(cd ../templating ; python build.py -i matrix_templates -o ../scripts/gen ../scripts/tmp/http_apis --substitution=%CLIENT_RELEASE_LABEL%="${client_release}" --substitution=%CLIENT_MAJOR_VERSION%="${client_major_version}") rst2html.py --stylesheet-path=$(echo css/*.css | tr ' ' ',') gen/http_apis > gen/http_apis.html diff --git a/specification/intro.rst b/specification/intro.rst index 211a3562..eb6f98fc 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -1,30 +1,20 @@ Matrix Specification ==================== -Version: {{spec_version}} ------------------------------ This specification has been generated from https://github.com/matrix-org/matrix-doc using https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of -revision ``{{git_version}}`` - https://github.com/matrix-org/matrix-doc/tree/{{git_rev}} +revision ``{{git_version}}`` - +https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}. -APIs ----- The following APIs are documented in this specification: -- `Client-Server API `_ for writing Matrix clients. -- `Server-Server API `_ for writing servers which can federate with Matrix. -- `Application Service API `_ for writing privileged plugins to servers. +- `Client-Server API `_ version %CLIENT_RELEASE_LABEL% for writing Matrix clients. +- `Server-Server API `_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix. +- `Application Service API `_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers. There are also some `appendices `_. -Changelog ---------- -{{spec_changelog}} - -For a full changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/CHANGELOG.rst - .. contents:: Table of Contents .. sectnum:: diff --git a/templating/build.py b/templating/build.py index 10fb5aea..f08c2201 100755 --- a/templating/build.py +++ b/templating/build.py @@ -44,6 +44,7 @@ import importlib import json import logging import os +import re import sys from textwrap import TextWrapper @@ -56,7 +57,7 @@ def check_unaccessed(name, store): log("Found %s unused %s keys." % (len(unaccessed_keys), name)) log(unaccessed_keys) -def main(input_module, file_stream=None, out_dir=None, verbose=False): +def main(input_module, file_stream=None, out_dir=None, verbose=False, substitutions={}): if out_dir and not os.path.exists(out_dir): os.makedirs(out_dir) @@ -167,6 +168,12 @@ def main(input_module, file_stream=None, out_dir=None, verbose=False): temp = Template(temp_str) log("Creating output for: %s" % file_stream.name) output = create_from_template(temp, sections) + + # Do these substitutions outside of the ordinary templating system because + # we want them to apply to things like the underlying swagger used to + # generate the templates, not just the top-level sections. + for old, new in substitutions.items(): + output = output.replace(old, new) with open( os.path.join(out_dir, os.path.basename(file_stream.name)), "w" ) as f: @@ -209,6 +216,10 @@ if __name__ == '__main__': "--verbose", "-v", action="store_true", help="Turn on verbose mode." ) + parser.add_argument( + "--substitution", action="append", + help="Substitutions to apply to the generated output, of form NEEDLE=REPLACEMENT." + ) args = parser.parse_args() if args.verbose: @@ -226,7 +237,14 @@ if __name__ == '__main__': parser.print_help() sys.exit(1) + substitutions = {} + for substitution in args.substitution: + parts = substitution.split("=", 1) + if len(parts) != 2: + raise Exception("Invalid substitution") + substitutions[parts[0]] = parts[1] + main( args.input, file_stream=args.file, out_dir=args.out_directory, - verbose=args.verbose + substitutions=substitutions, verbose=args.verbose ) diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 78aabca7..d285bb61 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -15,10 +15,6 @@ class MatrixSections(Sections): def render_git_rev(self): return self.units.get("git_version")["revision"] - def render_spec_version(self): - spec_meta = self.units.get("spec_meta") - return spec_meta["version"] - def render_spec_changelog(self): spec_meta = self.units.get("spec_meta") return spec_meta["changelog"] diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 06994082..feae0aae 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -18,8 +18,8 @@ import urllib import yaml HTTP_APIS = "../api/client-server" -V1_EVENT_EXAMPLES = "../event-schemas/examples" -V1_EVENT_SCHEMA = "../event-schemas/schema" +EVENT_EXAMPLES = "../event-schemas/examples" +EVENT_SCHEMA = "../event-schemas/schema" CORE_EVENT_SCHEMA = "../event-schemas/schema/core-event-schema" CHANGELOG = "../CHANGELOG.rst" TARGETS = "../specification/targets.yaml" @@ -605,7 +605,7 @@ class MatrixUnits(Units): return event_types def load_event_examples(self): - path = V1_EVENT_EXAMPLES + path = EVENT_EXAMPLES examples = {} for filename in os.listdir(path): if not filename.startswith("m."): @@ -622,7 +622,7 @@ class MatrixUnits(Units): return examples def load_event_schemas(self): - path = V1_EVENT_SCHEMA + path = EVENT_SCHEMA schemata = {} for filename in os.listdir(path): @@ -714,7 +714,6 @@ class MatrixUnits(Units): def load_spec_meta(self): path = CHANGELOG title_part = None - version = None changelog_lines = [] with open(path, "r") as f: prev_line = None @@ -738,19 +737,11 @@ class MatrixUnits(Units): break changelog_lines.append(line) - # parse out version from title - for word in title_part.split(): - if re.match("^v[0-9\.]+$", word): - version = word[1:] # strip the 'v' - - self.log("Version: %s Title part: %s Changelog line count: %s" % ( - version, title_part, len(changelog_lines) + self.log("Title part: %s Changelog line count: %s" % ( + title_part, len(changelog_lines) )) - if not version or len(changelog_lines) == 0: - raise Exception("Failed to parse CHANGELOG.rst") return { - "version": version, "changelog": "".join(changelog_lines) } From aa4ed10821220c0f1b43541ea61d611f1993908d Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 17:23:58 +0000 Subject: [PATCH 06/33] Unify v1 and v2 event schemas --- api/client-server/guest_events.yaml | 2 +- api/client-server/old_sync.yaml | 19 ++++---- api/client-server/presence.yaml | 3 +- api/client-server/rooms.yaml | 31 ++++++------- api/client-server/search.yaml | 2 +- event-schemas/examples/m.call.answer | 2 +- event-schemas/examples/m.call.candidates | 2 +- event-schemas/examples/m.call.hangup | 2 +- event-schemas/examples/m.call.invite | 2 +- event-schemas/examples/m.room.aliases | 2 +- event-schemas/examples/m.room.avatar | 2 +- event-schemas/examples/m.room.canonical_alias | 2 +- event-schemas/examples/m.room.create | 2 +- event-schemas/examples/m.room.guest_access | 2 +- .../examples/m.room.history_visibility | 2 +- event-schemas/examples/m.room.join_rules | 2 +- event-schemas/examples/m.room.member | 2 +- .../examples/m.room.member#invite_room_state | 2 +- .../examples/m.room.member#third_party_invite | 2 +- event-schemas/examples/m.room.message#m.audio | 4 +- event-schemas/examples/m.room.message#m.emote | 2 +- event-schemas/examples/m.room.message#m.file | 4 +- event-schemas/examples/m.room.message#m.image | 2 +- .../examples/m.room.message#m.location | 2 +- .../examples/m.room.message#m.notice | 2 +- event-schemas/examples/m.room.message#m.text | 2 +- event-schemas/examples/m.room.message#m.video | 4 +- .../examples/m.room.message.feedback | 2 +- event-schemas/examples/m.room.name | 2 +- event-schemas/examples/m.room.power_levels | 2 +- event-schemas/examples/m.room.redaction | 2 +- event-schemas/examples/m.room.topic | 2 +- event-schemas/examples/m.typing | 2 +- .../schema/core-event-schema/room_event.json | 34 +++++++++++---- specification/events.rst | 43 ++----------------- 35 files changed, 87 insertions(+), 109 deletions(-) diff --git a/api/client-server/guest_events.yaml b/api/client-server/guest_events.yaml index 671b355a..4d7a957d 100644 --- a/api/client-server/guest_events.yaml +++ b/api/client-server/guest_events.yaml @@ -74,7 +74,7 @@ paths: "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", - "user_id": "@bob:localhost" + "sender": "@bob:localhost" } ] } diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml index 6dbe7e5e..fe76e3bc 100644 --- a/api/client-server/old_sync.yaml +++ b/api/client-server/old_sync.yaml @@ -60,7 +60,7 @@ paths: "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", - "user_id": "@bob:localhost" + "sender": "@bob:localhost" } ] } @@ -154,7 +154,7 @@ paths: "origin_server_ts": 1432804485886, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", - "user_id": "@alice:localhost" + "sender": "@alice:localhost" }, { "age": 343511809, @@ -166,7 +166,7 @@ paths: "origin_server_ts": 1432804487480, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "type": "m.room.message", - "user_id": "@bob:localhost" + "sender": "@bob:localhost" } ], "end": "s3456_9_0", @@ -184,13 +184,12 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.join_rules", - "user_id": "@alice:localhost" + "sender": "@alice:localhost" }, { "age": 6547561012, "content": { "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto", - "displayname": null, "membership": "join" }, "event_id": "$1426600438280zExKY:localhost", @@ -199,7 +198,7 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "@alice:localhost", "type": "m.room.member", - "user_id": "@alice:localhost" + "sender": "@alice:localhost" }, { "age": 7148267200, @@ -211,7 +210,7 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.create", - "user_id": "@alice:localhost" + "sender": "@alice:localhost" }, { "age": 1622568720, @@ -226,7 +225,7 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "@bob:localhost", "type": "m.room.member", - "user_id": "@bob:localhost" + "sender": "@bob:localhost" }, { "age": 7148267004, @@ -250,7 +249,7 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state_key": "", "type": "m.room.power_levels", - "user_id": "@alice:localhost" + "sender": "@alice:localhost" } ], "visibility": "private", @@ -392,7 +391,7 @@ paths: "msgtype": "m.text" }, "room_id:": "!wfgy43Sg4a:matrix.org", - "user_id": "@bob:matrix.org", + "sender": "@bob:matrix.org", "event_id": "$asfDuShaf7Gafaw:matrix.org", "type": "m.room.message" } diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index 33df17d2..6ac204dd 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -85,8 +85,7 @@ paths: application/json: |- { "presence": "unavailable", - "last_active_ago": 420845, - "status_msg": null + "last_active_ago": 420845 } schema: type: object diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index f7654f14..cc3aecc4 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -92,13 +92,12 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.join_rules", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "displayname": null, "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", @@ -107,7 +106,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 7148267200, @@ -119,7 +118,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.create", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 1622568720, @@ -134,7 +133,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", - "user_id": "@bob:example.com" + "sender": "@bob:example.com" }, { "age": 7148267004, @@ -158,7 +157,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.power_levels", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" } ] schema: @@ -212,7 +211,7 @@ paths: "origin_server_ts": 1432804485886, "room_id": "!636q39766251:example.com", "type": "m.room.message", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 343511809, @@ -224,7 +223,7 @@ paths: "origin_server_ts": 1432804487480, "room_id": "!636q39766251:example.com", "type": "m.room.message", - "user_id": "@bob:example.com" + "sender": "@bob:example.com" } ], "end": "s3456_9_0", @@ -242,13 +241,12 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.join_rules", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "displayname": null, "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", @@ -257,7 +255,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 7148267200, @@ -269,7 +267,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.create", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 1622568720, @@ -284,7 +282,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", - "user_id": "@bob:example.com" + "sender": "@bob:example.com" }, { "age": 7148267004, @@ -308,7 +306,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "", "type": "m.room.power_levels", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" } ], "visibility": "private", @@ -416,7 +414,6 @@ paths: "age": 6547561012, "content": { "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "displayname": null, "membership": "join" }, "event_id": "$1426600438280zExKY:example.com", @@ -425,7 +422,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@alice:example.com", "type": "m.room.member", - "user_id": "@alice:example.com" + "sender": "@alice:example.com" }, { "age": 1622568720, @@ -440,7 +437,7 @@ paths: "room_id": "!636q39766251:example.com", "state_key": "@bob:example.com", "type": "m.room.member", - "user_id": "@bob:example.com" + "sender": "@bob:example.com" } ] } diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 3da9486f..8a8c3f5a 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -131,7 +131,7 @@ paths: "origin_server_ts": 1444298308034, "room_id": "!qPewotXpIctQySfjSy:localhost", "type": "m.room.message", - "user_id": "@test:localhost" + "sender": "@test:localhost" } } } diff --git a/event-schemas/examples/m.call.answer b/event-schemas/examples/m.call.answer index 0301fb3b..f7d14439 100644 --- a/event-schemas/examples/m.call.answer +++ b/event-schemas/examples/m.call.answer @@ -13,5 +13,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.call.answer", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.call.candidates b/event-schemas/examples/m.call.candidates index 389d2271..8e6849bb 100644 --- a/event-schemas/examples/m.call.candidates +++ b/event-schemas/examples/m.call.candidates @@ -15,5 +15,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.call.candidates", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.call.hangup b/event-schemas/examples/m.call.hangup index 52ddad16..42e1f346 100644 --- a/event-schemas/examples/m.call.hangup +++ b/event-schemas/examples/m.call.hangup @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.call.hangup", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.call.invite b/event-schemas/examples/m.call.invite index 2df25929..974a5b4c 100644 --- a/event-schemas/examples/m.call.invite +++ b/event-schemas/examples/m.call.invite @@ -13,5 +13,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.call.invite", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.aliases b/event-schemas/examples/m.room.aliases index 07b4b330..ca87510e 100644 --- a/event-schemas/examples/m.room.aliases +++ b/event-schemas/examples/m.room.aliases @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.aliases", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.avatar b/event-schemas/examples/m.room.avatar index 9fb1189c..2080d96e 100644 --- a/event-schemas/examples/m.room.avatar +++ b/event-schemas/examples/m.room.avatar @@ -14,5 +14,5 @@ "type": "m.room.avatar", "state_key": "", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.canonical_alias b/event-schemas/examples/m.room.canonical_alias index 0203a851..59df586d 100644 --- a/event-schemas/examples/m.room.canonical_alias +++ b/event-schemas/examples/m.room.canonical_alias @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.canonical_alias", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.create b/event-schemas/examples/m.room.create index a3598853..34dabb53 100644 --- a/event-schemas/examples/m.room.create +++ b/event-schemas/examples/m.room.create @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.create", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.guest_access b/event-schemas/examples/m.room.guest_access index 8ad4d294..c636ff39 100644 --- a/event-schemas/examples/m.room.guest_access +++ b/event-schemas/examples/m.room.guest_access @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEG:localhost", "type": "m.room.guest_access", "room_id": "!Cuyf34gef24u:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.history_visibility b/event-schemas/examples/m.room.history_visibility index fcc3f881..6fedc5dc 100644 --- a/event-schemas/examples/m.room.history_visibility +++ b/event-schemas/examples/m.room.history_visibility @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.history_visibility", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.join_rules b/event-schemas/examples/m.room.join_rules index f22ad97e..39e14fc5 100644 --- a/event-schemas/examples/m.room.join_rules +++ b/event-schemas/examples/m.room.join_rules @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.join_rules", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.member b/event-schemas/examples/m.room.member index e2ca5668..133cad96 100644 --- a/event-schemas/examples/m.room.member +++ b/event-schemas/examples/m.room.member @@ -26,5 +26,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.member", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member#invite_room_state index e2ca5668..133cad96 100644 --- a/event-schemas/examples/m.room.member#invite_room_state +++ b/event-schemas/examples/m.room.member#invite_room_state @@ -26,5 +26,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.member", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.member#third_party_invite b/event-schemas/examples/m.room.member#third_party_invite index 2457302a..1bae2e9f 100644 --- a/event-schemas/examples/m.room.member#third_party_invite +++ b/event-schemas/examples/m.room.member#third_party_invite @@ -21,5 +21,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.member", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.audio b/event-schemas/examples/m.room.message#m.audio index b57adc9a..367eb954 100644 --- a/event-schemas/examples/m.room.message#m.audio +++ b/event-schemas/examples/m.room.message#m.audio @@ -14,5 +14,5 @@ "origin_server_ts": 1432735824653, "room_id": "!jEsUZKDJdhlrceRyVU:localhost", "type": "m.room.message", - "user_id": "@example:localhost" -} \ No newline at end of file + "sender": "@example:localhost" +} diff --git a/event-schemas/examples/m.room.message#m.emote b/event-schemas/examples/m.room.message#m.emote index bd984831..4280928e 100644 --- a/event-schemas/examples/m.room.message#m.emote +++ b/event-schemas/examples/m.room.message#m.emote @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.message", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.file b/event-schemas/examples/m.room.message#m.file index 7ac36c90..e52c3a94 100644 --- a/event-schemas/examples/m.room.message#m.file +++ b/event-schemas/examples/m.room.message#m.file @@ -14,5 +14,5 @@ "origin_server_ts": 1432735824653, "room_id": "!jEsUZKDJdhlrceRyVU:localhost", "type": "m.room.message", - "user_id": "@example:localhost" -} \ No newline at end of file + "sender": "@example:localhost" +} diff --git a/event-schemas/examples/m.room.message#m.image b/event-schemas/examples/m.room.message#m.image index ba405a1a..91e72be2 100644 --- a/event-schemas/examples/m.room.message#m.image +++ b/event-schemas/examples/m.room.message#m.image @@ -15,5 +15,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.message", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.location b/event-schemas/examples/m.room.message#m.location index 54198acb..fcbeb97e 100644 --- a/event-schemas/examples/m.room.message#m.location +++ b/event-schemas/examples/m.room.message#m.location @@ -16,5 +16,5 @@ "origin_server_ts": 1432735824653, "room_id": "!jEsUZKDJdhlrceRyVU:localhost", "type": "m.room.message", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.notice b/event-schemas/examples/m.room.message#m.notice index 2e5fff97..978c67e6 100644 --- a/event-schemas/examples/m.room.message#m.notice +++ b/event-schemas/examples/m.room.message#m.notice @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.message", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.text b/event-schemas/examples/m.room.message#m.text index d877ee64..e00c7aa5 100644 --- a/event-schemas/examples/m.room.message#m.text +++ b/event-schemas/examples/m.room.message#m.text @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.message", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.message#m.video b/event-schemas/examples/m.room.message#m.video index e3da9077..576d80de 100644 --- a/event-schemas/examples/m.room.message#m.video +++ b/event-schemas/examples/m.room.message#m.video @@ -23,5 +23,5 @@ "origin_server_ts": 1432735824653, "room_id": "!jEsUZKDJdhlrceRyVU:localhost", "type": "m.room.message", - "user_id": "@example:localhost" -} \ No newline at end of file + "sender": "@example:localhost" +} diff --git a/event-schemas/examples/m.room.message.feedback b/event-schemas/examples/m.room.message.feedback index 6282305b..16fe0ee0 100644 --- a/event-schemas/examples/m.room.message.feedback +++ b/event-schemas/examples/m.room.message.feedback @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.message.feedback", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.name b/event-schemas/examples/m.room.name index 636119b8..87db2008 100644 --- a/event-schemas/examples/m.room.name +++ b/event-schemas/examples/m.room.name @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.name", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.power_levels b/event-schemas/examples/m.room.power_levels index 8278597a..42ef5a5d 100644 --- a/event-schemas/examples/m.room.power_levels +++ b/event-schemas/examples/m.room.power_levels @@ -20,5 +20,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.power_levels", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.redaction b/event-schemas/examples/m.room.redaction index 2e8260ea..5f4aae1e 100644 --- a/event-schemas/examples/m.room.redaction +++ b/event-schemas/examples/m.room.redaction @@ -8,5 +8,5 @@ "type": "m.room.redaction", "room_id": "!Cuyf34gef24t:localhost", "redacts": "!fukweghifu23:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.room.topic b/event-schemas/examples/m.room.topic index 8a469122..65daa987 100644 --- a/event-schemas/examples/m.room.topic +++ b/event-schemas/examples/m.room.topic @@ -8,5 +8,5 @@ "event_id": "$WLGTSEFSEF:localhost", "type": "m.room.topic", "room_id": "!Cuyf34gef24t:localhost", - "user_id": "@example:localhost" + "sender": "@example:localhost" } diff --git a/event-schemas/examples/m.typing b/event-schemas/examples/m.typing index bd53f6fb..1d2c517b 100644 --- a/event-schemas/examples/m.typing +++ b/event-schemas/examples/m.typing @@ -4,4 +4,4 @@ "content": { "user_ids": ["@alice:matrix.org", "@bob:example.com"] } -} \ No newline at end of file +} diff --git a/event-schemas/schema/core-event-schema/room_event.json b/event-schemas/schema/core-event-schema/room_event.json index 80f7d265..09cb2478 100644 --- a/event-schemas/schema/core-event-schema/room_event.json +++ b/event-schemas/schema/core-event-schema/room_event.json @@ -1,23 +1,41 @@ { "type": "object", "title": "Room Event", - "description": "In addition to the Event fields, Room Events MUST have the following additional field.", + "description": "In addition to the Event fields, Room Events may have the following additional fields.", "allOf":[{ "$ref": "event.json" }], "properties": { - "room_id": { + "event_id": { "type": "string", - "description": "The ID of the room associated with this event." + "description": "Required. The globally unique event identifier." }, - "event_id": { + "room_id": { "type": "string", - "description": "The globally unique event identifier." + "description": "Required. The ID of the room associated with this event." }, - "user_id": { + "sender": { "type": "string", - "description": "Contains the fully-qualified ID of the user who *sent* this event." + "description": "Required. Contains the fully-qualified ID of the user who *sent* this event." + }, + "unsigned": { + "type": "object", + "description": "Contains optional extra information about the event.", + "properties": { + "age": { + "type": "integer", + "description": "The time in milliseconds that has elapsed since the event was sent" + }, + "redacted_because": { + "type": "string", + "description": "The reason this event was redacted, if it was redacted" + }, + "transaction_id": { + "type": "string", + "description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it." + } + } } }, - "required": ["room_id"] + "required": ["event_id", "room_id", "sender"] } diff --git a/specification/events.rst b/specification/events.rst index 5a003115..92d52d22 100644 --- a/specification/events.rst +++ b/specification/events.rst @@ -5,6 +5,9 @@ All communication in Matrix is expressed in the form of data objects called Events. These are the fundamental building blocks common to the client-server, server-server and application-service APIs, and are described below. +Note that the structure of these events may be different than those in the +server-server API. + {{common_event_fields}} {{common_room_event_fields}} @@ -12,51 +15,13 @@ server-server and application-service APIs, and are described below. {{common_state_event_fields}} -Differences between /v1 and /v2 events --------------------------------------- - -There are a few differences between how events are formatted for sending -between servers over federation and how they are formatted for sending between -a server and its clients. - -Additionally there are a few differences between the format of events in the -responses to client APIs with a /v1 prefix and responses APIs with a /v2 -prefix. - -Events in responses for APIs with the /v2 prefix are generated from an event -formatted for federation by: - -* Removing the following keys: - ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``, - ``origin``, ``prev_state``. -* Adding an ``age`` to the ``unsigned`` object which gives the time in - milliseconds that has elapsed since the event was sent. -* Adding ``prev_content`` and ``prev_sender`` to the ``unsigned`` object if the - event is a ``state event``, which give the previous content and previous - sender of that state key -* Adding a ``redacted_because`` to the ``unsigned`` object if the event was - redacted which gives the event that redacted it. -* Adding a ``transaction_id`` to the ``unsigned`` object if the event was sent - by the client requesting it. - -Events in responses for APIs with the /v1 prefix are generated from an event -formatted for the /v2 prefix by: - -* Moving the folling keys from the ``unsigned`` object to the top level event - object: ``age``, ``redacted_because``, ``replaces_state``, ``prev_content``. -* Removing the ``unsigned`` object. -* Rename the ``sender`` key to ``user_id``. -* If the event was an ``m.room.member`` with ``membership`` set to ``invite`` - then adding a ``invite_room_state`` key to the top level event object. - - Size limits ----------- The total size of any event MUST NOT exceed 65 KB. There are additional restrictions on sizes per key: -- ``user_id`` MUST NOT exceed 255 bytes (including domain). +- ``sender`` MUST NOT exceed 255 bytes (including domain). - ``room_id`` MUST NOT exceed 255 bytes. - ``state_key`` MUST NOT exceed 255 bytes. - ``type`` MUST NOT exceed 255 bytes. From 7f07da4b507f6d0c20a8b17cab23276d9d050d7f Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 1 Dec 2015 17:29:09 +0000 Subject: [PATCH 07/33] Remove obsolete documentation --- api/client-server/definitions/event.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/api/client-server/definitions/event.json b/api/client-server/definitions/event.json index 5a8f52f6..98aac21e 100644 --- a/api/client-server/definitions/event.json +++ b/api/client-server/definitions/event.json @@ -39,10 +39,6 @@ "type": "object", "description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing." }, - "replaces_state": { - "type": "string", - "description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing." - }, "transaction_id": { "type": "string", "description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API." From b946d398864343180ca96837f56916d726bbb8cb Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Wed, 2 Dec 2015 01:25:07 +0000 Subject: [PATCH 08/33] typo --- specification/modules/search.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/search.rst b/specification/modules/search.rst index 089953d2..655b1ed3 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -34,7 +34,7 @@ The supported keys to search over are: The search will *not* include rooms that are end to end encrypted. The results include a ``rank`` key that can be used to sort the results by -revelancy. The higher the ``rank`` the more relevant the result is. +relevancy. The higher the ``rank`` the more relevant the result is. The value of ``count`` may not match the number of results. For example due to the search query matching 1000s of results and the server truncating the From 1ce33579270f86ef2c85601a5eb6423fdd009d9f Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 2 Dec 2015 14:53:52 +0000 Subject: [PATCH 09/33] continuserv: serve multiple paths --- scripts/continuserv/main.go | 44 ++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/scripts/continuserv/main.go b/scripts/continuserv/main.go index 14d0c5bf..a1295077 100644 --- a/scripts/continuserv/main.go +++ b/scripts/continuserv/main.go @@ -26,7 +26,7 @@ var ( port = flag.Int("port", 8000, "Port on which to serve HTTP") mu sync.Mutex // Prevent multiple updates in parallel. - toServe atomic.Value // Always contains valid []byte to serve. May be stale unless wg is zero. + toServe atomic.Value // Always contains a bytesOrErr. May be stale unless wg is zero. wgMu sync.Mutex // Prevent multiple calls to wg.Wait() or wg.Add(positive number) in parallel. wg sync.WaitGroup // Indicates how many updates are pending. @@ -116,14 +116,29 @@ func serve(w http.ResponseWriter, req *http.Request) { wgMu.Lock() wg.Wait() wgMu.Unlock() - b := toServe.Load().(bytesOrErr) - if b.err != nil { + + file := req.URL.Path + if file[0] == '/' { + file = file[1:] + } + if file == "" { + file = "index.html" + } + m := toServe.Load().(bytesOrErr) + if m.err != nil { w.Header().Set("Content-Type", "text/plain") - w.Write([]byte(b.err.Error())) - } else { + w.Write([]byte(m.err.Error())) + return + } + b, ok := m.bytes[file] + if ok { w.Header().Set("Content-Type", "text/html") - w.Write([]byte(b.bytes)) + w.Write([]byte(b)) + return } + w.Header().Set("Content-Type", "text/plain") + w.WriteHeader(404) + w.Write([]byte("Not found")) } func populateOnce(dir string) { @@ -139,12 +154,21 @@ func populateOnce(dir string) { toServe.Store(bytesOrErr{nil, fmt.Errorf("error generating spec: %v\nOutput from gendoc:\n%v", err, b.String())}) return } - specBytes, err := ioutil.ReadFile(path.Join(dir, "scripts", "gen", "specification.html")) + fis, err := ioutil.ReadDir(path.Join(dir, "scripts", "gen")) if err != nil { - toServe.Store(bytesOrErr{nil, fmt.Errorf("error reading spec: %v", err)}) + toServe.Store(bytesOrErr{nil, err}) return } - toServe.Store(bytesOrErr{specBytes, nil}) + files := make(map[string][]byte) + for _, fi := range fis { + bytes, err := ioutil.ReadFile(path.Join(dir, "scripts", "gen", fi.Name())) + if err != nil { + toServe.Store(bytesOrErr{nil, fmt.Errorf("error reading spec: %v", err)}) + return + } + files[fi.Name()] = bytes + } + toServe.Store(bytesOrErr{files, nil}) } func doPopulate(ch chan struct{}, dir string) { @@ -173,6 +197,6 @@ func exists(path string) bool { } type bytesOrErr struct { - bytes []byte + bytes map[string][]byte // filename -> contents err error } From e072d215cf466e76552a6eb53dc9e1cea8a4838c Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 2 Dec 2015 15:27:25 +0000 Subject: [PATCH 10/33] Specify redaction --- api/client-server/redaction.yaml | 82 +++++++++++++++++++++++++++++ specification/client_server_api.rst | 17 +++--- 2 files changed, 92 insertions(+), 7 deletions(-) create mode 100644 api/client-server/redaction.yaml diff --git a/api/client-server/redaction.yaml b/api/client-server/redaction.yaml new file mode 100644 index 00000000..d30ef8c1 --- /dev/null +++ b/api/client-server/redaction.yaml @@ -0,0 +1,82 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server message redaction API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/rooms/{roomId}/redact/{eventId}/{txnId}": + put: + summary: Strips all non-integrity-critical information out of an event. + description: |- + Strips all information out of an event which isn't critical to the + integrity of the server-side representation of the room. + + This cannot be undone. + + Users may redact their own events, and any user with a power level + greater than or equal to the `redact` power level of the room may + redact events there. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room from which to redact the event. + required: true + x-example: "!637q39766251:example.com" + - in: path + type: string + name: eventId + description: The ID of the event to redact + required: true + x-example: "bai2b1i9:matrix.org" + - in: path + name: txnId + type: string + description: |- + The transaction ID for this event. Clients should generate a + unique ID; it will be used by the server to ensure idempotency of requests. + required: true + x-example: "37" + - in: body + name: body + schema: + type: object + example: |- + { + "reason": "Indecent material" + } + properties: + reason: + type: string + description: The reason for the event being redacted. + responses: + 200: + description: "An ID for the redaction event." + examples: + application/json: |- + { + "event_id": "YUwQidLecu" + } + schema: + type: object + properties: + event_id: + type: string + description: |- + A unique identifier for the event. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 67973c6b..4c24c350 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -793,10 +793,6 @@ owners to delete the offending content from the databases. Events that have been redacted include a ``redacted_because`` key whose value is the event that caused it to be redacted, which may include a reason. -.. TODO - Currently, only room admins can redact events by sending a ``m.room.redaction`` - event, but server admins also need to be able to redact events by a similar - mechanism. Upon receipt of a redaction event, the server should strip off any keys not in the following list: @@ -819,13 +815,20 @@ one of the following event types: ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``. - ``m.room.aliases`` allows key ``aliases`` -.. TODO - Need to update m.room.power_levels to reflect new power levels formatting - The redaction event should be added under the key ``redacted_because``. When a client receives a redaction event it should change the redacted event in the same way a server does. +Events +++++++ + +{{m_room_redaction_event}} + +Client behaviour +++++++++++++++++ + +{{redaction_http_api}} + Rooms ----- From 2f3a00fe34b2414484ab2c2265c571d84db9328b Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 2 Dec 2015 19:23:33 +0000 Subject: [PATCH 11/33] Consistently spell homeserver as homeserver --- api/client-server/administrative_contact.yaml | 6 +- api/client-server/create_room.yaml | 2 +- api/client-server/inviting.yaml | 2 +- api/client-server/login.yaml | 2 +- api/client-server/pusher.yaml | 2 +- api/client-server/registration.yaml | 4 +- api/client-server/third_party_membership.yaml | 4 +- attic/v1_registration_login.rst | 48 ++++++++-------- ...ient_federated_versioning_design_notes.rst | 8 +-- drafts/as-http-api.rst | 42 +++++++------- drafts/erikj_federation.rst | 6 +- drafts/general_api.rst | 54 +++++++++--------- drafts/human-id-rules.rst | 14 ++--- drafts/model/presence.rst | 12 ++-- drafts/model/profiles.rst | 16 +++--- drafts/model/room-join-workflow.rst | 12 ++-- drafts/model/rooms.rst | 20 +++---- drafts/model/third-party-id.rst | 2 +- scripts/generate-http-docs.sh | 2 +- specification/application_service_api.rst | 14 ++--- specification/client_server_api.rst | 56 +++++++++---------- specification/intro.rst | 4 +- specification/modules/presence.rst | 4 +- specification/modules/push.rst | 2 +- specification/server_server_api.rst | 50 ++++++++--------- .../examples/application-services.rst | 8 +-- .../guides/2015-08-10-client-server.rst | 16 +++--- .../guides/2015-08-21-application_services.md | 18 +++--- supporting-docs/howtos/client-server.rst | 16 +++--- .../jsfiddles/create_room_send_msg/demo.html | 2 +- .../jsfiddles/create_room_send_msg/demo.js | 2 +- .../howtos/jsfiddles/event_stream/demo.html | 2 +- .../howtos/jsfiddles/event_stream/demo.js | 2 +- .../howtos/jsfiddles/example_app/demo.html | 2 +- .../howtos/jsfiddles/example_app/demo.js | 4 +- .../howtos/jsfiddles/register_login/demo.html | 2 +- .../howtos/jsfiddles/register_login/demo.js | 4 +- .../jsfiddles/room_memberships/demo.html | 2 +- .../howtos/jsfiddles/room_memberships/demo.js | 2 +- 39 files changed, 235 insertions(+), 235 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 68fd0fba..7e3f8bce 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -25,7 +25,7 @@ paths: This API endpoint uses the User-Interactive Authentication API. An access token should be submitted to this endpoint if the client has an active session. - The Home Server may change the flows available depending on whether a + The homeserver may change the flows available depending on whether a valid access token is provided. security: - accessToken: [] @@ -64,7 +64,7 @@ paths: This is *not* the same as the list of third party identifiers bound to the user's Matrix ID in Identity Servers. - Identifiers in this list may be used by the Home Server as, for example, + Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password. security: - accessToken: [] @@ -126,7 +126,7 @@ paths: bind: type: boolean description: |- - Whether the home server should also bind this third party + Whether the homeserver should also bind this third party identifier to the account's Matrix ID with the passed identity server. Default: ``false``. x-example: true diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 051c4b84..20c00f6c 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -57,7 +57,7 @@ paths: description: |- The desired room alias **local part**. If this is included, a room alias will be created and mapped to the newly created - room. The alias will belong on the *same* home server which + room. The alias will belong on the *same* homeserver which created the room. For example, if this was set to "foo" and sent to the homeserver "example.com" the complete room alias would be ``#foo:example.com``. diff --git a/api/client-server/inviting.yaml b/api/client-server/inviting.yaml index 0a028710..d9b0ad10 100644 --- a/api/client-server/inviting.yaml +++ b/api/client-server/inviting.yaml @@ -38,7 +38,7 @@ paths: Only users currently in a particular room can invite other users to join that room. - If the user was invited to the room, the home server will append a + If the user was invited to the room, the homeserver will append a ``m.room.member`` event to the room. .. _third party invites section: `invite-by-third-party-id-endpoint`_ diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index bbab46df..f2e3d044 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -81,7 +81,7 @@ paths: (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. home_server: type: string - description: The hostname of the Home Server on which the account has been registered. + description: The hostname of the homeserver on which the account has been registered. 400: description: |- Part of the request was invalid. For example, the login type may not be recognised. diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 8c243f2b..ed6c4f91 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -114,7 +114,7 @@ paths: description: |- If true, the homeserver should add another pusher with the given pushkey and App ID in addition to any others with - different user IDs. Otherwise, the Home Server must remove any + different user IDs. Otherwise, the homeserver must remove any other pushers with the same App ID and pushkey for different users. The default is ``false``. required: ['profile_tag', 'kind', 'app_id', 'app_display_name', diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 681654ae..7bb49f2c 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -94,7 +94,7 @@ paths: (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. home_server: type: string - description: The hostname of the Home Server on which the account has been registered. + description: The hostname of the homeserver on which the account has been registered. 400: description: |- Part of the request was invalid. This may include one of the following error codes: @@ -107,7 +107,7 @@ paths: including after authentication if the requested user ID was registered whilst the client was performing authentication. - Home Servers MUST perform the relevant checks and return these codes before + Homeservers MUST perform the relevant checks and return these codes before performing `User-Interactive Authentication`_, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication. diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index a10d6167..e9c4d2f2 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -39,7 +39,7 @@ paths: join that room. If the identity server did know the Matrix user identifier for the - third party identifier, the home server will append a ``m.room.member`` + third party identifier, the homeserver will append a ``m.room.member`` event to the room. If the identity server does not know a Matrix user identifier for the @@ -62,7 +62,7 @@ paths: - The matrix user ID who invited them to the room - If a token is requested from the identity server, the home server will + If a token is requested from the identity server, the homeserver will append a ``m.room.third_party_invite`` event to the room. .. _joining rooms section: `invite-by-user-id-endpoint`_ diff --git a/attic/v1_registration_login.rst b/attic/v1_registration_login.rst index 4b80600b..1364319b 100644 --- a/attic/v1_registration_login.rst +++ b/attic/v1_registration_login.rst @@ -1,17 +1,17 @@ Registration and Login ---------------------- -Clients must register with a home server in order to use Matrix. After +Clients must register with a homeserver in order to use Matrix. After registering, the client will be given an access token which must be used in ALL -requests to that home server as a query parameter 'access_token'. +requests to that homeserver as a query parameter 'access_token'. If the client has already registered, they need to be able to login to their -account. The home server may provide many different ways of logging in, such as +account. The homeserver may provide many different ways of logging in, such as user/password auth, login via a social network (OAuth2), login by confirming a token sent to their email address, etc. This specification does not define how -home servers should authorise their users who want to login to their existing +homeservers should authorise their users who want to login to their existing accounts, but instead defines the standard interface which implementations -should follow so that ANY client can login to ANY home server. Clients login +should follow so that ANY client can login to ANY homeserver. Clients login using the |login|_ API. Clients register using the |register|_ API. Registration follows the same general procedure as login, but the path requests are sent to and the details contained in them are different. @@ -26,7 +26,7 @@ In order to determine up-front what the server's requirements are, the client can request from the server a complete description of all of its acceptable flows of the registration or login process. It can then inspect the list of returned flows looking for one for which it believes it can complete all of the -required stages, and perform it. As each home server may have different ways of +required stages, and perform it. As each homeserver may have different ways of logging in, the client needs to know how they should login. All distinct login stages MUST have a corresponding ``type``. A ``type`` is a namespaced string which details the mechanism for logging in. @@ -64,12 +64,12 @@ ID and a new access token MUST be returned:: "access_token": "abcdef0123456789" } -The ``user_id`` key is particularly useful if the home server wishes to support +The ``user_id`` key is particularly useful if the homeserver wishes to support localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as the client may not be able to determine its ``user_id`` in this case. -If the flow has multiple stages to it, the home server may wish to create a -session to store context between requests. If a home server responds with a +If the flow has multiple stages to it, the homeserver may wish to create a +session to store context between requests. If a homeserver responds with a ``session`` key to a request, clients MUST submit it in subsequent requests until the flow is completed:: @@ -99,7 +99,7 @@ To respond to this type, reply with:: "password": "" } -The home server MUST respond with either new credentials, the next stage of the +The homeserver MUST respond with either new credentials, the next stage of the login process, or a standard error response. Captcha-based @@ -123,7 +123,7 @@ To respond to this type, reply with:: Recaptcha.get_challenge(); Recaptcha.get_response(); -The home server MUST respond with either new credentials, the next stage of the +The homeserver MUST respond with either new credentials, the next stage of the login process, or a standard error response. OAuth2-based @@ -146,24 +146,24 @@ The server MUST respond with:: "uri": } -The home server acts as a 'confidential' client for the purposes of OAuth2. If +The homeserver acts as a 'confidential' client for the purposes of OAuth2. If the uri is a ``sevice selection URI``, it MUST point to a webpage which prompts the user to choose which service to authorize with. On selection of a service, this MUST link through to an ``Authorization Request URI``. If there is only 1 -service which the home server accepts when logging in, this indirection can be +service which the homeserver accepts when logging in, this indirection can be skipped and the "uri" key can be the ``Authorization Request URI``. The client then visits the ``Authorization Request URI``, which then shows the OAuth2 Allow/Deny prompt. Hitting 'Allow' returns the ``redirect URI`` with the -auth code. Home servers can choose any path for the ``redirect URI``. The +auth code. Homeservers can choose any path for the ``redirect URI``. The client should visit the ``redirect URI``, which will then finish the OAuth2 -login process, granting the home server an access token for the chosen service. -When the home server gets this access token, it verifies that the cilent has +login process, granting the homeserver an access token for the chosen service. +When the homeserver gets this access token, it verifies that the cilent has authorised with the 3rd party, and can now complete the login. The OAuth2 ``redirect URI`` (with auth code) MUST respond with either new credentials, the next stage of the login process, or a standard error response. -For example, if a home server accepts OAuth2 from Google, it would return the +For example, if a homeserver accepts OAuth2 from Google, it would return the Authorization Request URI for Google:: { @@ -171,7 +171,7 @@ Authorization Request URI for Google:: client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos" } -The client then visits this URI and authorizes the home server. The client then +The client then visits this URI and authorizes the homeserver. The client then visits the REDIRECT_URI with the auth code= query parameter which returns:: { @@ -195,7 +195,7 @@ To respond to this type, reply with:: "email": "" } -After validating the email address, the home server MUST send an email +After validating the email address, the homeserver MUST send an email containing an authentication code and return:: { @@ -212,7 +212,7 @@ code:: "code": "" } -The home server MUST respond to this with either new credentials, the next +The homeserver MUST respond to this with either new credentials, the next stage of the login process, or a standard error response. Email-based (url) @@ -231,7 +231,7 @@ To respond to this type, reply with:: "email": "" } -After validating the email address, the home server MUST send an email +After validating the email address, the homeserver MUST send an email containing an authentication URL and return:: { @@ -247,7 +247,7 @@ client should perform another request:: "session": "" } -The home server MUST respond to this with either new credentials, the next +The homeserver MUST respond to this with either new credentials, the next stage of the login process, or a standard error response. A common client implementation will be to periodically poll until the link is @@ -264,7 +264,7 @@ Email-based (identity server) Prior to submitting this, the client should authenticate with an identity server. After authenticating, the session information should be submitted to -the home server. +the homeserver. To respond to this type, reply with:: @@ -293,7 +293,7 @@ of a previous login stage:: "next": "" } -If a home server implements N-factor authentication, it MUST respond with all +If a homeserver implements N-factor authentication, it MUST respond with all ``stages`` when initially queried for their login requirements:: { diff --git a/drafts/ancient_federated_versioning_design_notes.rst b/drafts/ancient_federated_versioning_design_notes.rst index ffda6063..036989eb 100644 --- a/drafts/ancient_federated_versioning_design_notes.rst +++ b/drafts/ancient_federated_versioning_design_notes.rst @@ -1,11 +1,11 @@ -Versioning is, like, hard for backfilling backwards because of the number of Home Servers involved. +Versioning is, like, hard for backfilling backwards because of the number of homeservers involved. -The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis. +The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis. When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C. Problems with opaque version strings: - - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote home server at a time. + - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote homeserver at a time. If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION. - - How do you do backfilling? A version string defines a point in a stream w.r.t. a single home server, not a point in the context. + - How do you do backfilling? A version string defines a point in a stream w.r.t. a single homeserver, not a point in the context. We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges. diff --git a/drafts/as-http-api.rst b/drafts/as-http-api.rst index 2c8f8e37..4f8d6bd4 100644 --- a/drafts/as-http-api.rst +++ b/drafts/as-http-api.rst @@ -13,9 +13,9 @@ Application Services HTTP API .. sectnum:: -Application Service -> Home Server +Application Service -> Homeserver ---------------------------------- -This contains home server APIs which are used by the application service. +This contains homeserver APIs which are used by the application service. Registration API ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -34,7 +34,7 @@ Output: Side effects: - The HS will start delivering events to the URL base specified if this 200s. API called when: - - The application service wants to register with a brand new home server. + - The application service wants to register with a brand new homeserver. Notes: - An application service can state whether they should be the only ones who can manage a specified namespace. This is referred to as an "exclusive" @@ -100,7 +100,7 @@ Notes: Unregister API ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -This API unregisters a previously registered AS from the home server. +This API unregisters a previously registered AS from the homeserver. Inputs: - AS token @@ -122,9 +122,9 @@ API called when: } -Home Server -> Application Service +Homeserver -> Application Service ---------------------------------- -This contains application service APIs which are used by the home server. +This contains application service APIs which are used by the homeserver. User Query ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~ @@ -152,9 +152,9 @@ Notes: - This is deemed more flexible than alternative methods (e.g. returning a JSON blob with the user's display name and get the HS to provision the user). Retry notes: - - The home server cannot respond to the client's request until the response to + - The homeserver cannot respond to the client's request until the response to this API is obtained from the AS. - - Recommended that home servers try a few times then time out, returning a + - Recommended that homeservers try a few times then time out, returning a 408 Request Timeout to the client. :: @@ -199,9 +199,9 @@ Notes: style JSON blob and get the HS to provision the room). It also means that the AS knows the room ID -> alias mapping. Retry notes: - - The home server cannot respond to the client's request until the response to + - The homeserver cannot respond to the client's request until the response to this API is obtained from the AS. - - Recommended that home servers try a few times then time out, returning a + - Recommended that homeservers try a few times then time out, returning a 408 Request Timeout to the client. :: @@ -236,13 +236,13 @@ Data flows: :: Typical - HS ---> AS : Home server sends events with transaction ID T. + HS ---> AS : Homeserver sends events with transaction ID T. <--- : AS sends back 200 OK. AS ACK Lost - HS ---> AS : Home server sends events with transaction ID T. + HS ---> AS : Homeserver sends events with transaction ID T. <-/- : AS 200 OK is lost. - HS ---> AS : Home server retries with the same transaction ID of T. + HS ---> AS : Homeserver retries with the same transaction ID of T. <--- : AS sends back 200 OK. If the AS had processed these events already, it can NO-OP this request (and it knows if it is the same events based on the transacton ID). @@ -253,15 +253,15 @@ Retry notes: - Since ASes by definition cannot alter the traffic being passed to it (unlike say, a Policy Server), these requests can be done in parallel to general HS processing; the HS doesn't need to block whilst doing this. - - Home servers should use exponential backoff as their retry algorithm. - - Home servers MUST NOT alter (e.g. add more) events they were going to + - Homeservers should use exponential backoff as their retry algorithm. + - Homeservers MUST NOT alter (e.g. add more) events they were going to send within that transaction ID on retries, as the AS may have already processed the events. Ordering notes: - The events sent to the AS should be linearised, as they are from the event stream. - - The home server will need to maintain a queue of transactions to send to + - The homeserver will need to maintain a queue of transactions to send to the AS. :: @@ -336,7 +336,7 @@ Notes: Server admin style permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The home server needs to give the application service *full control* over its +The homeserver needs to give the application service *full control* over its namespace, both for users and for room aliases. This means that the AS should be able to create/edit/delete any room alias in its namespace, as well as create/delete any user in its namespace. No additional API changes need to be @@ -451,15 +451,15 @@ Examples IRC ~~~ Pre-conditions: - - Server admin stores the AS token "T_a" on the home server. - - Home server has a token "T_h". - - Home server has the domain "hsdomain.com" + - Server admin stores the AS token "T_a" on the homeserver. + - Homeserver has a token "T_h". + - Homeserver has the domain "hsdomain.com" 1. Application service registration :: - AS -> HS: Registers itself with the home server + AS -> HS: Registers itself with the homeserver POST /register { url: "https://someapp.com/matrix", diff --git a/drafts/erikj_federation.rst b/drafts/erikj_federation.rst index 0644f271..ce089def 100644 --- a/drafts/erikj_federation.rst +++ b/drafts/erikj_federation.rst @@ -237,7 +237,7 @@ Domain specific string ``room_id`` A domain specific string with prefix ``!`` that is static across all events in a graph and uniquely identifies it. The ``domain`` should be that of the - home server that created the room (i.e., the server that generated the + homeserver that created the room (i.e., the server that generated the first ``m.room.create`` event). ``sender`` @@ -246,7 +246,7 @@ Domain specific string User Id A domain specific string with prefix ``@`` representing a user account. The - ``domain`` is the home server of the user and is the server used to contact + ``domain`` is the homeserver of the user and is the server used to contact the user. Joining a room @@ -280,7 +280,7 @@ can then process the join event itself. Inviting a user --------------- -To invite a remote user to a room we need their home server to sign the invite +To invite a remote user to a room we need their homeserver to sign the invite event. This is done by sending the event to the remote server, which then signs the event, before distributing the invite to other servers. diff --git a/drafts/general_api.rst b/drafts/general_api.rst index ae2446d6..baad3901 100644 --- a/drafts/general_api.rst +++ b/drafts/general_api.rst @@ -61,7 +61,7 @@ This version will change the path prefix for HTTP: - Version 2: ``/_matrix/client/v2`` Note the lack of the ``api`` segment. This is for consistency between other -home server path prefixes. +homeserver path prefixes. Terminology: - ``Chunk token`` : An opaque string which can be used to return another chunk @@ -169,16 +169,16 @@ Outputs: ``content`` key. Deleted message events are ``m.room.redaction`` events. - New position in the stream. (chunk token) State Events Ordering Notes: - - Home servers may receive state events over federation that are superceded by - state events previously sent to the client. The home server *cannot* send + - Homeservers may receive state events over federation that are superceded by + state events previously sent to the client. The homeserver *cannot* send these events to the client else they would end up erroneously clobbering the superceding state event. - - As a result, the home server reserves the right to omit sending state events + - As a result, the homeserver reserves the right to omit sending state events which are known to be superceded already. - This may result in missed *state* events. However, the state of the room will always be eventually consistent. Message Events Ordering Notes: - - Home servers may receive message events over federation that happened a long + - Homeservers may receive message events over federation that happened a long time ago. The client may or may not be interested in these message events. - For clients which do not store scrollback for a room (they discard events after processing them), this is not a problem as they only care about the @@ -191,11 +191,11 @@ Message Events Ordering Notes: - The event, when it comes down the stream, will indicate which event it comes after. Rejected events: - - A home server may find out via federation that it should not have accepted + - A homeserver may find out via federation that it should not have accepted an event (e.g. to send a message/state event in a room). For example, it may - send an event to another home server and receive an auth event stating + send an event to another homeserver and receive an auth event stating that the event should not have been sent. - - If this happens, the home server will send a ``m.room.redaction`` for the + - If this happens, the homeserver will send a ``m.room.redaction`` for the event in question. This will be a local server event (not shared with other servers). - If the event was a state event, it will synthesise a new state event to @@ -206,7 +206,7 @@ Unknown rooms: - You could receive events for rooms you are unaware of (e.g. you didn't do an initial sync, or your HS lost its database and is told from another HS that they are in this room). How do you handle this? - - The simplest option would be to redo the initial sync with a filter on the + - The simplest option would be to redo the initial sync with a filter on the room ID you're unaware of. This would retrieve the room state so you can display the room. What data flows does it address: @@ -291,7 +291,7 @@ Scrollback API ``[Draft]`` but as a purely informational display thing it would be nice. Additional Inputs: - - flag to say if the home server should do a backfill over federation + - flag to say if the homeserver should do a backfill over federation Additional Outputs: - whether there are more events on the local HS / over federation. What data flows does it address: @@ -313,7 +313,7 @@ Additional Outputs: Room Alias API ``[Draft]`` -------------------------- This provides mechanisms for creating and removing room aliases for a room on a -home server. Typically, any user in a room can make an alias for that room. The +homeserver. Typically, any user in a room can make an alias for that room. The alias creator (or anyone in the room?) can delete that alias. Server admins can also delete any alias on their server. @@ -323,7 +323,7 @@ Inputs: - Room Alias Output: - Room ID - - List of home servers to join via. + - List of homeservers to join via. Mapping a room to an alias: @@ -334,7 +334,7 @@ Inputs: Output: - Room alias Notes: - - The home server may add restrictions e.g. the user must be in the room. + - The homeserver may add restrictions e.g. the user must be in the room. Deleting a mapping: @@ -347,11 +347,11 @@ Output: Published room list API ``[Draft]`` ----------------------------------- -This provides mechanisms for searching for published rooms on a home server. +This provides mechanisms for searching for published rooms on a homeserver. Inputs: - Search text (e.g. room alias/name/topic to search on) - - Home server to search on (this may just be the URL hit for HTTP) + - Homeserver to search on (this may just be the URL hit for HTTP) - Any existing pagination token, can be missing if this is the first hit. - Limit for pagination Output: @@ -378,7 +378,7 @@ Notes: User Profile API ``[Draft]`` ---------------------------- -Every user on a home server has a profile. This profile is effectively a +Every user on a homeserver has a profile. This profile is effectively a key-value store scoped to a user ID. It can include an ``avatar_url``, ``displayname`` and other metadata. Updates to a profile should propagate to other interested users. @@ -435,7 +435,7 @@ This had a number of problems associated with it: flicker. - Name/avatar changes created more ``m.room.member`` events which meant they needed to be included in the auth chains for federation. This - created long auth chains which is suboptimal since home servers need + created long auth chains which is suboptimal since homeservers need to store the auth chains forever. These problems can be resolved by creating an ``m.room.member.profile`` @@ -448,7 +448,7 @@ However, this introduces its own set of problems, namely flicker. The client would receive the ``m.room.member`` event first, followed by the ``m.room.member.profile`` event, which could cause a flicker. In addition, federation may not send both events in a single transaction, -resulting in missing information on the receiving home server. +resulting in missing information on the receiving homeserver. For federation, these problems can be resolved by sending the ``m.room.member`` event as they are in v1 (with ``displayname`` and @@ -457,7 +457,7 @@ they cannot be in the ``unsigned`` part of the event. The receiving home server will then extract these keys and create a server-generated ``m.room.member.profile`` event. To avoid confusion with duplicate information, the ``avatar_url`` and ``displayname`` keys should be -removed from the ``m.room.member`` event by the receiving home server. +removed from the ``m.room.member`` event by the receiving homeserver. When a client requests these events (either from the event stream or from an initial sync), the server will send the generated ``m.room.member.profile`` event under the ``unsigned.profile`` key of the @@ -840,17 +840,17 @@ information per device to all other users just redirects the union problem to the client, which will commonly be presenting this information as an icon alongside the user. -When a client hits the event stream, the home server can treat the user as +When a client hits the event stream, the homeserver can treat the user as "online". This behaviour should be able to be overridden to avoid flicker during connection losses when the client is appear offline (e.g. device is appear offline > goes into a tunnel > server times out > device regains connection and hits the event stream forcing the device online before the "appear offline" state can be set). When the client has not hit the event -stream for a certain period of time, the home server can treat the user as +stream for a certain period of time, the homeserver can treat the user as "offline". The user can also set a global *per-user* appear offline flag. The user should also be able to set their presence state via a direct API, -without having to hit the event stream. The home server will set a timer when +without having to hit the event stream. The homeserver will set a timer when the connection ends, after which it will set that device to offline. As the idle flag and online state is determined per device, there needs to be a @@ -970,12 +970,12 @@ the hashes the same is the best as that means clients do not need to request the capabilities for the given hash. On first signup, the client will attempt to send the hash and be most likely -refused by the home server as it does not know the full capability set for that +refused by the homeserver as it does not know the full capability set for that hash. The client will then have to upload the full capability set to the home server. The client will then be able to send the hash as normal. When a client receives a hash, the client will either recognise the hash or -will have to request the capability set from their home server: +will have to request the capability set from their homeserver: Inputs: - Hash @@ -1070,7 +1070,7 @@ Main use cases for ``updates``: - Call signalling (child events are ICE candidates, answer to the offer, and termination) - *Local* Delivery/Read receipts : "Local" means they are not shared with other - users on the same home server or via federation but *are* shared between + users on the same homeserver or via federation but *are* shared between clients for the same user; useful for push notifications, read count markers, etc. This is done to avoid the ``n^2`` problem for sending receipts, where the vast majority of traffic tends towards sending more receipts. @@ -1168,11 +1168,11 @@ Events (breaking changes; event version 2) ``[Draft]`` when dealing with custom event types. E.g. ``_custom.event`` would allow anything in the state key, ``_@custom.event`` would only allow user IDs in the state key, etc. -- s/user_id/sender/g given that home servers can send events, not just users. +- s/user_id/sender/g given that homeservers can send events, not just users. Server-generated events ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Home servers may want to send events to their local clients or to other home +Homeservers may want to send events to their local clients or to other home servers e.g. for server status notifications. These events look like regular events but have a server domain name as the diff --git a/drafts/human-id-rules.rst b/drafts/human-id-rules.rst index 914a9a42..d0c2ee2c 100644 --- a/drafts/human-id-rules.rst +++ b/drafts/human-id-rules.rst @@ -13,9 +13,9 @@ phishing/spoofing of IDs, commonly known as a homograph attack. Web browers encountered this problem when International Domain Names were introduced. A variety of checks were put in place in order to protect users. If an address failed the check, the raw punycode would be displayed to -disambiguate the address. Similar checks are performed by home servers in +disambiguate the address. Similar checks are performed by homeservers in Matrix. However, Matrix does not use punycode representations, and so does not -show raw punycode on a failed check. Instead, home servers must outright reject +show raw punycode on a failed check. Instead, homeservers must outright reject these misleading IDs. Types of human-readable IDs @@ -48,12 +48,12 @@ Checks Rejecting --------- -- Home servers MUST reject room aliases which do not pass the check, both on +- Homeservers MUST reject room aliases which do not pass the check, both on GETs and PUTs. -- Home servers MUST reject user ID localparts which do not pass the check, both +- Homeservers MUST reject user ID localparts which do not pass the check, both on creation and on events. -- Any home server whose domain does not pass this check, MUST use their punycode - domain name instead of the IDN, to prevent other home servers rejecting you. +- Any homeserver whose domain does not pass this check, MUST use their punycode + domain name instead of the IDN, to prevent other homeservers rejecting you. - Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing due to homograph attacks, and failing due to including ``:`` s, etc) - Error message MAY go into further information about which characters were @@ -74,7 +74,7 @@ Other considerations - High security: Outright rejection of the ID at the point of creation / receiving event. Point of creation rejection is preferable to avoid the ID entering the system in the first place. However, malicious HSes can just - allow the ID. Hence, other home servers must reject them if they see them in + allow the ID. Hence, other homeservers must reject them if they see them in events. Client never sees the problem ID, provided the HS is correctly implemented. - High security decided; client doesn't need to worry about it, no additional diff --git a/drafts/model/presence.rst b/drafts/model/presence.rst index bd60cba0..c2c88737 100644 --- a/drafts/model/presence.rst +++ b/drafts/model/presence.rst @@ -5,14 +5,14 @@ A simple implementation of presence messaging has the ability to cause a large amount of Internet traffic relating to presence updates. In order to minimise the impact of such a feature, the following observations can be made: - * There is no point in a Home Server polling status for peers in a user's + * There is no point in a homeserver polling status for peers in a user's presence list if the user has no clients connected that care about it. * It is highly likely that most presence subscriptions will be symmetric - a given user watching another is likely to in turn be watched by that user. * It is likely that most subscription pairings will be between users who share - at least one Room in common, and so their Home Servers are actively + at least one Room in common, and so their homeservers are actively exchanging message PDUs or transactions relating to that Room. * Presence update messages do not need realtime guarantees. It is acceptable to @@ -25,7 +25,7 @@ promise to send them when required. Rather than actively polling for the current state all the time, HSes can rely on their relative stability to only push updates when required. -A Home Server should not rely on the longterm validity of this presence +A homeserver should not rely on the longterm validity of this presence information, however, as this would not cover such cases as a user's server crashing and thus failing to inform their peers that users it used to host are no longer available online. Therefore, each promise of future updates should @@ -33,7 +33,7 @@ carry with a timeout value (whether explicit in the message, or implicit as some defined default in the protocol), after which the receiving HS should consider the information potentially stale and request it again. -However, because of the likelihood that two home servers are exchanging messages +However, because of the likelihood that two homeservers are exchanging messages relating to chat traffic in a room common to both of them, the ongoing receipt of these messages can be taken by each server as an implicit notification that the sending server is still up and running, and therefore that no status changes @@ -98,7 +98,7 @@ The data model presented here puts the following requirements on the APIs: Client-Server ------------- -Requests that a client can make to its Home Server +Requests that a client can make to its homeserver * get/set current presence state Basic enumeration + ability to set a custom piece of text @@ -128,7 +128,7 @@ Requests that a client can make to its Home Server Server-Server ------------- -Requests that Home Servers make to others +Requests that homeservers make to others * request permission to add a user to presence list diff --git a/drafts/model/profiles.rst b/drafts/model/profiles.rst index 15f65feb..f81e115e 100644 --- a/drafts/model/profiles.rst +++ b/drafts/model/profiles.rst @@ -9,7 +9,7 @@ Overview ======== Internally within Synapse users are referred to by an opaque ID, which consists -of some opaque localpart combined with the domain name of their home server. +of some opaque localpart combined with the domain name of their homeserver. Obviously this does not yield a very nice user experience; users would like to see readable names for other users that are in some way meaningful to them. Additionally, users like to be able to publish "profile" details to inform other @@ -59,7 +59,7 @@ servers should be accounted for here.]] Visibility Permissions ====================== -A home server implementation could offer the ability to set permissions on +A homeserver implementation could offer the ability to set permissions on limited visibility of those fields. When another user requests access to the target user's profile, their own identity should form part of that request. The HS implementation can then decide which fields to make available to the @@ -130,12 +130,12 @@ namespace to allocate names into. It would also be nice from a user experience perspective if the profile that a given name links to can also declare that name as part of its metadata. Furthermore as a security and consistency perspective it would be nice if each -end (the directory server and the user's home server) check the validity of the +end (the directory server and the user's homeserver) check the validity of the mapping in some way. This needs investigation from a security perspective to ensure against spoofing. One such model may be that the user starts by declaring their intent to use a -given user name link to their home server, which then contacts the directory +given user name link to their homeserver, which then contacts the directory service. At some point later (maybe immediately for "public open FCFS servers", maybe after some kind of human intervention for verification) the DS decides to honour this link, and includes it in its served output. It should also tell the @@ -170,7 +170,7 @@ balancing choice on behalf of the user who would choose, or not, to make use of such a feature to publish their information. Additionally, unless some form of strong end-to-end user-based encryption is -used, a user of ACLs for information privacy has to trust other home servers not +used, a user of ACLs for information privacy has to trust other homeservers not to lie about the identify of the user requesting access to the Profile. @@ -182,7 +182,7 @@ The data model presented here puts the following requirements on the APIs: Client-Server ------------- -Requests that a client can make to its Home Server +Requests that a client can make to its homeserver * get/set my Display Name This should return/take a simple "text/plain" field @@ -207,7 +207,7 @@ TODO(paul): At some later stage we should consider the API for: Server-Server ------------- -Requests that Home Servers make to others +Requests that homeservers make to others * get a user's Display Name / Avatar @@ -221,7 +221,7 @@ Requests that Home Servers make to others Room Event PDU Types -------------------- -Events that are pushed from Home Servers to other Home Servers or clients. +Events that are pushed from homeservers to other homeservers or clients. * user Display Name change diff --git a/drafts/model/room-join-workflow.rst b/drafts/model/room-join-workflow.rst index c321a64f..ff469740 100644 --- a/drafts/model/room-join-workflow.rst +++ b/drafts/model/room-join-workflow.rst @@ -8,7 +8,7 @@ Discovery ========= To join a room, a user has to discover the room by some mechanism in order to -obtain the (opaque) Room ID and a candidate list of likely home servers that +obtain the (opaque) Room ID and a candidate list of likely homeservers that contain it. Sending an Invitation @@ -21,7 +21,7 @@ The inviter's HS sets the membership status of the invitee to "invited" in the "m.members" state key by sending a state update PDU. The HS then broadcasts this PDU among the existing members in the usual way. An invitation message is also sent to the invited user, containing the Room ID and the PDU ID of this -invitation state change and potentially a list of some other home servers to use +invitation state change and potentially a list of some other homeservers to use to accept the invite. The user's client can then choose to display it in some way to alert the user. @@ -34,7 +34,7 @@ Directory Service Alternatively, the user may discover the channel via a directory service; either by performing a name lookup, or some kind of browse or search acitivty. However -this is performed, the end result is that the user's home server requests the +this is performed, the end result is that the user's homeserver requests the Room ID and candidate list from the directory service. [[TODO(paul): At present, no API has been designed or described for this @@ -44,14 +44,14 @@ directory service]] Joining ======= -Once the ID and home servers are obtained, the user can then actually join the +Once the ID and homeservers are obtained, the user can then actually join the room. Accepting an Invite ------------------- If a user has received and accepted an invitation to join a room, the invitee's -home server can now send an invite acceptance message to a chosen candidate +homeserver can now send an invite acceptance message to a chosen candidate server from the list given in the invitation, citing also the PDU ID of the invitation as "proof" of their invite. (This is required as due to late message propagation it could be the case that the acceptance is received before the @@ -85,7 +85,7 @@ can instead post a "knock" message, which informs other members of the room that the would-be joiner wishes to become a member and sets their membership value to "knocked". If any of them wish to accept this, they can then send an invitation in the usual way described above. Knowing that the user has already knocked and -expressed an interest in joining, the invited user's home server should +expressed an interest in joining, the invited user's homeserver should immediately accept that invitation on the user's behalf, and go on to join the room in the usual way. diff --git a/drafts/model/rooms.rst b/drafts/model/rooms.rst index 07c5e71f..2f57f2bc 100644 --- a/drafts/model/rooms.rst +++ b/drafts/model/rooms.rst @@ -18,19 +18,19 @@ users, and other management and miscellaneous metadata), and a message history. Room Identity and Naming ======================== -Rooms can be arbitrarily created by any user on any home server; at which point -the home server will sign the message that creates the channel, and the +Rooms can be arbitrarily created by any user on any homeserver; at which point +the homeserver will sign the message that creates the channel, and the fingerprint of this signature becomes the strong persistent identify of the -room. This now identifies the room to any home server in the network regardless +room. This now identifies the room to any homeserver in the network regardless of its original origin. This allows the identify of the room to outlive any particular server. Subject to appropriate permissions [to be discussed later], any current member of a room can invite others to join it, can post messages that become part of its history, and can change the persistent state of the room (including its current set of permissions). -Home servers can provide a directory service, allowing a lookup from a +Homeservers can provide a directory service, allowing a lookup from a convenient human-readable form of room label to a room ID. This mapping is -scoped to the particular home server domain and so simply represents that server +scoped to the particular homeserver domain and so simply represents that server administrator's opinion of what room should take that label; it does not have to be globally replicated and does not form part of the stored state of that room. @@ -156,7 +156,7 @@ m.public_history to be a member of the room. m.archive_servers - For "public" rooms with public history, gives a list of home servers that + For "public" rooms with public history, gives a list of homeservers that should be included in message distribution to the room, even if no users on that server are present. These ensure that a public room can still persist even if no users are currently members of it. This list should be consulted by @@ -179,7 +179,7 @@ m.topic Room Creation Templates ======================= -A client (or maybe home server?) could offer a few templates for the creation of +A client (or maybe homeserver?) could offer a few templates for the creation of new rooms. For example, for a simple private one-to-one chat the channel could assign the creator a power-level of 1, requiring a level of 1 to invite, and needing an invite before members can join. An invite is then sent to the other @@ -215,7 +215,7 @@ permissions to allow this direct messaging. Between any given pair of user IDs that wish to exchange private messages, there will exist a single shared Room, created lazily by either side. These rooms will -need a certain amount of special handling in both home servers and display on +need a certain amount of special handling in both homeservers and display on clients, but as much as possible should be treated by the lower layers of code the same as other rooms. @@ -226,7 +226,7 @@ clients should display these in a special way too as the room name is not important; instead it should distinguish them on the Display Name of the other party. -Home Servers will need a client-API option to request setting up a new user-user +Homeservers will need a client-API option to request setting up a new user-user chat room, which will then need special handling within the server. It will create a new room with the following @@ -260,7 +260,7 @@ history with each other simultaneously create a room and invite the other to it. This is called a "glare" situation. There are two possible ideas for how to resolve this: - * Each Home Server should persist the mapping of (user ID pair) to room ID, so + * Each homeserver should persist the mapping of (user ID pair) to room ID, so that duplicate requests can be suppressed. On receipt of a room creation request that the HS thinks there already exists a room for, the invitation to join can be rejected if: diff --git a/drafts/model/third-party-id.rst b/drafts/model/third-party-id.rst index 1f8138dd..838a6799 100644 --- a/drafts/model/third-party-id.rst +++ b/drafts/model/third-party-id.rst @@ -66,7 +66,7 @@ Privacy A User may publish the association between their phone number and Matrix User ID on the Identity Server without publishing the number in their Profile hosted on -their Home Server. +their homeserver. Identity Servers should refrain from publishing reverse mappings and should take steps, such as rate limiting, to prevent attackers enumerating the space of diff --git a/scripts/generate-http-docs.sh b/scripts/generate-http-docs.sh index 48c01bdb..41a65296 100755 --- a/scripts/generate-http-docs.sh +++ b/scripts/generate-http-docs.sh @@ -24,7 +24,7 @@ cat >tmp/http_apis < Application Service API +Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pushing events @@ -101,13 +101,13 @@ events. Each list of events includes a transaction ID, which works as follows: :: Typical - HS ---> AS : Home server sends events with transaction ID T. + HS ---> AS : Homeserver sends events with transaction ID T. <--- : AS sends back 200 OK. AS ACK Lost - HS ---> AS : Home server sends events with transaction ID T. + HS ---> AS : Homeserver sends events with transaction ID T. <-/- : AS 200 OK is lost. - HS ---> AS : Home server retries with the same transaction ID of T. + HS ---> AS : Homeserver retries with the same transaction ID of T. <--- : AS sends back 200 OK. If the AS had processed these events already, it can NO-OP this request (and it knows if it is the same events based on the transaction ID). @@ -145,7 +145,7 @@ this request (e.g. to join a room alias). HTTP APIs +++++++++ -This contains application service APIs which are used by the home server. All +This contains application service APIs which are used by the homeserver. All application services MUST implement these APIs. These APIs are defined below. {{application_service_http_api}} @@ -158,7 +158,7 @@ Client-Server v2 API Extensions Application services can utilise a more powerful version of the client-server API by identifying itself as an application service to the -home server. +homeserver. Identity assertion ++++++++++++++++++ @@ -212,7 +212,7 @@ Server admin style permissions .. _sect:asapi-permissions: -The home server needs to give the application service *full control* over its +The homeserver needs to give the application service *full control* over its namespace, both for users and for room aliases. This means that the AS should be able to create/edit/delete any room alias in its namespace, as well as create/delete any user in its namespace. No additional API changes need to be diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 67973c6b..9edf7e55 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -147,12 +147,12 @@ User-Interactive Authentication API This section refers to API Version 2. Some API endpoints such as ``login`` or ``register`` require authentication that -interacts with the user. The home server may provide many different ways of +interacts with the user. The homeserver may provide many different ways of authenticating, such as user/password auth, login via a social network (OAuth2), login by confirming a token sent to their email address, etc. This specification -does not define how home servers should authorise their users but instead +does not define how homeservers should authorise their users but instead defines the standard interface which implementations should follow so that ANY -client can login to ANY home server. +client can login to ANY homeserver. The process takes the form of one or more stages, where at each stage the client submits a set of data for a given stage type and awaits a response from the @@ -168,9 +168,9 @@ more than one stage to implement n-factor auth. When all stages are complete, authentication is complete and the API call succeeds. To establish what flows a server supports for an endpoint, a client sends the request with no authentication. A request to an endpoint that uses User-Interactive -Authentication never succeeds without auth. Home Servers may allow requests that +Authentication never succeeds without auth. Homeservers may allow requests that don't require auth by offering a stage with only the ``m.login.dummy`` auth -type. The home server returns a response with HTTP status 401 and a JSON object +type. The homeserver returns a response with HTTP status 401 and a JSON object as follows:: { @@ -208,7 +208,7 @@ does this by resubmitting the same request with the the addition of an 'auth' key in the object that it submits. This dictionary contains a ``type`` key whose value is the name of the stage type that the client is attempting to complete. It must also contains a ``session`` key with the value of the session key given -by the home server, if one was given. It also contains other keys dependent on +by the homeserver, if one was given. It also contains other keys dependent on the stage type being attempted. For example, if the client is attempting to complete login type ``example.type.foo``, it might submit something like this:: @@ -222,7 +222,7 @@ complete login type ``example.type.foo``, it might submit something like this:: } } -If the home server deems the authentication attempt to be successful but still +If the homeserver deems the authentication attempt to be successful but still requires more stages to be completed, it returns HTTP status 401 along with the same object as when no authentication was attempted, with the addition of the ``completed`` key which is an array of stage type the client has completed @@ -246,7 +246,7 @@ successfully:: "session": "xxxxxx" } -If the home server decides the attempt was unsuccessful, it returns an error +If the homeserver decides the attempt was unsuccessful, it returns an error message in the standard format:: { @@ -258,7 +258,7 @@ Individual stages may require more than one request to complete, in which case the response will be as if the request was unauthenticated with the addition of any other keys as defined by the login type. -If the client has completed all stages of a flow, the home server performs the +If the client has completed all stages of a flow, the homeserver performs the API call and returns the result as normal. Some authentication types may be completed by means other than through the @@ -389,16 +389,16 @@ OAuth2-based ``uri``: Authorization Request URI OR service selection URI. Both contain an encoded ``redirect URI``. -The home server acts as a 'confidential' client for the purposes of OAuth2. If +The homeserver acts as a 'confidential' client for the purposes of OAuth2. If the uri is a ``service selection URI``, it MUST point to a webpage which prompts the user to choose which service to authorize with. On selection of a service, this MUST link through to an ``Authorization Request URI``. If there is only one -service which the home server accepts when logging in, this indirection can be +service which the homeserver accepts when logging in, this indirection can be skipped and the "uri" key can be the ``Authorization Request URI``. The client then visits the ``Authorization Request URI``, which then shows the OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the ``redirect URI`` with -the auth code. Home servers can choose any path for the ``redirect URI``. Once +the auth code. Homeservers can choose any path for the ``redirect URI``. Once the OAuth flow has completed, the client retries the request with the session only, as above. @@ -412,7 +412,7 @@ Email-based (identity server) Prior to submitting this, the client should authenticate with an identity server. After authenticating, the session information should be submitted to -the home server. +the homeserver. To respond to this type, reply with an auth dict as follows:: @@ -450,12 +450,12 @@ Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login type, it can direct the user to a web browser with the URL of a fallback page which will allow the user to complete that login step out-of-band in their web browser. The URL it -should open is the Home Server base URL plus prefix, plus:: +should open is the homeserver base URL plus prefix, plus:: /auth//fallback/web?session= Where ``stage type`` is the type name of the stage it is attempting and -``session id`` is the ID of the session given by the home server. +``session id`` is the ID of the session given by the homeserver. This MUST return an HTML page which can perform this authentication stage. This page must attempt to call the JavaScript function ``window.onAuthDone`` when @@ -494,7 +494,7 @@ Request:: This API endpoint uses the User-Interactive Authentication API. An access token should be submitted to this endpoint if the client has an active session. The -Home Server may change the flows available depending on whether a valid access +homeserver may change the flows available depending on whether a valid access token is provided. The body of the POST request is a JSON object containing: @@ -505,7 +505,7 @@ new_password On success, an empty JSON object is returned. The error code M_NOT_FOUND is returned if the user authenticated with a third -party identifier but the Home Server could not find a matching account in its +party identifier but the homeserver could not find a matching account in its database. Adding Account Administrative Contact Information @@ -699,7 +699,7 @@ namespaced for each application and reduces the risk of clashes. Syncing ~~~~~~~ -Clients receive new events by "long-polling" the home server via the events API. +Clients receive new events by "long-polling" the homeserver via the events API. This involves specifying a timeout in the request which will hold open the HTTP connection for a short period of time waiting for new events, returning early if an event occurs. Only the events API supports long-polling. @@ -719,7 +719,7 @@ last request left off. Multiple events can be returned per long-poll. Do we ever support streaming requests? Why not websockets? When the client first logs in, they will need to initially synchronise with -their home server. This is achieved via the initial sync API described below. +their homeserver. This is achieved via the initial sync API described below. This API also returns an ``end`` token which can be used with the event stream. {{old_sync_http_api}} @@ -831,7 +831,7 @@ Rooms Creation ~~~~~~~~ -The home server will create an ``m.room.create`` event when a room is created, +The homeserver will create an ``m.room.create`` event when a room is created, which serves as the root of the event graph for this room. This event also has a ``creator`` key which contains the user ID of the room creator. It will also generate several other events in order to manage permissions in this room. This @@ -852,9 +852,9 @@ Room aliases Servers may host aliases for rooms with human-friendly names. Aliases take the form ``#friendlyname:server.name``. -As room aliases are scoped to a particular home server domain name, it is -likely that a home server will reject attempts to maintain aliases on other -domain names. This specification does not provide a way for home servers to +As room aliases are scoped to a particular homeserver domain name, it is +likely that a homeserver will reject attempts to maintain aliases on other +domain names. This specification does not provide a way for homeservers to send update requests to other servers. Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state @@ -867,8 +867,8 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked to make sure that the room's ID matches the ``room_id`` returned from the request. -Home servers can respond to resolve requests for aliases on other domains than -their own by using the federation API to ask other domain name home servers. +Homeservers can respond to resolve requests for aliases on other domains than +their own by using the federation API to ask other domain name homeservers. {{directory_http_api}} @@ -985,10 +985,10 @@ values. This change is conveyed using two separate mechanisms: values of the ``displayname`` and ``avatar_url`` keys, in addition to the required ``presence`` key containing the current presence state of the user. -Both of these should be done automatically by the home server when a user +Both of these should be done automatically by the homeserver when a user successfully changes their display name or avatar URL fields. -Additionally, when home servers emit room membership events for their own +Additionally, when homeservers emit room membership events for their own users, they should include the display name and avatar URL fields in these events so that clients already have these details to hand, and do not have to perform extra round trips to query it. @@ -998,7 +998,7 @@ Security Rate limiting ~~~~~~~~~~~~~ -Home servers SHOULD implement rate limiting to reduce the risk of being +Homeservers SHOULD implement rate limiting to reduce the risk of being overloaded. If a request is refused due to rate limiting, it should return a standard error response of the form:: diff --git a/specification/intro.rst b/specification/intro.rst index eb6f98fc..ced721fa 100644 --- a/specification/intro.rst +++ b/specification/intro.rst @@ -140,7 +140,7 @@ a long-lived GET request. | V | V +------------------+ +------------------+ | |---------( HTTPS )--------->| | - | Home Server | | Home Server | + | homeserver | | homeserver | | |<--------( HTTPS )----------| | +------------------+ Server-Server API +------------------+ History Synchronisation @@ -227,7 +227,7 @@ They are case-sensitive. The following conceptual diagram shows an | | V | +------------------+ +------------------+ - | Home Server | | Home Server | + | homeserver | | homeserver | | matrix.org | | domain.com | +------------------+ +------------------+ | ^ diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 3602d105..4eddaeee 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -61,7 +61,7 @@ recommended. Server behaviour ---------------- -Each user's home server stores a "presence list" per user. Once a user accepts +Each user's homeserver stores a "presence list" per user. Once a user accepts a presence list, both user's HSes must track the subscription. Propagating profile information @@ -73,7 +73,7 @@ automatic propagation event to occur, informing likely-interested parties of the new values. One of these change mechanisms SHOULD be via ``m.presence`` events. These events should set ``displayname`` and ``avatar_url`` to the new values along with the presence-specific keys. This SHOULD be done automatically by the -home server when a user successfully changes their display name or avatar URL. +homeserver when a user successfully changes their display name or avatar URL. .. admonition:: Rationale diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 893e9481..de45bfe6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -11,7 +11,7 @@ Push Notifications | | | | +-------------------+ | +----------------+ | | +---------------+ | | | | | | | | | | | - | Matrix Home Server+-----> Push Gateway +------> Push Provider | | + | Matrix homeserver+-----> Push Gateway +------> Push Provider | | | | | | | | | | | | +-^-----------------+ | +----------------+ | | +----+----------+ | | | | | | | diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 012c2ac9..ba6b7d35 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1,8 +1,8 @@ Federation API ============== -Matrix home servers use the Federation APIs (also known as server-server APIs) -to communicate with each other. Home servers use these APIs to push messages to +Matrix homeservers use the Federation APIs (also known as server-server APIs) +to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to request historic messages from each other, and to query profile and presence information about users on each other's servers. @@ -11,10 +11,10 @@ servers. These HTTPS requests are strongly authenticated using public key signatures at the TLS transport layer and using public key signatures in HTTP Authorization headers at the HTTP layer. -There are three main kinds of communication that occur between home servers: +There are three main kinds of communication that occur between homeservers: Persisted Data Units (PDUs): - These events are broadcast from one home server to any others that have + These events are broadcast from one homeserver to any others that have joined the same room (identified by Room ID). They are persisted in long-term storage and record the history of messages and state for a room. @@ -25,9 +25,9 @@ Persisted Data Units (PDUs): deliver them through third-party servers. Ephemeral Data Units (EDUs): - These events are pushed between pairs of home servers. They are not + These events are pushed between pairs of homeservers. They are not persisted and are not part of the history of a room, nor does the - receiving home server have to reply to them. + receiving homeserver have to reply to them. Queries: These are single request/response interactions between a given pair of @@ -38,7 +38,7 @@ Queries: EDUs and PDUs are further wrapped in an envelope called a Transaction, which is -transferred from the origin to the destination home server using an HTTPS PUT +transferred from the origin to the destination homeserver using an HTTPS PUT request. .. contents:: Table of Contents @@ -50,7 +50,7 @@ Server Discovery Resolving Server Names ~~~~~~~~~~~~~~~~~~~~~~ -Each matrix home server is identified by a server name consisting of a DNS name +Each matrix homeserver is identified by a server name consisting of a DNS name and an optional TLS port. .. code:: @@ -67,7 +67,7 @@ is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV record for the DNS name. If this record does not exist then the server is discovered by looking up an AAAA or A record on the DNS name and taking the default fallback port number of 8448. -Home servers may use SRV records to load balance requests between multiple TLS +Homeservers may use SRV records to load balance requests between multiple TLS endpoints or to failover to another endpoint if an endpoint fails. Retrieving Server Keys @@ -76,8 +76,8 @@ Retrieving Server Keys Version 2 +++++++++ -Each home server publishes its public keys under ``/_matrix/key/v2/server/``. -Home servers query for keys by either getting ``/_matrix/key/v2/server/`` +Each homeserver publishes its public keys under ``/_matrix/key/v2/server/``. +Homeservers query for keys by either getting ``/_matrix/key/v2/server/`` directly or by querying an intermediate notary server using a ``/_matrix/key/v2/query`` API. Intermediate notary servers query the ``/_matrix/key/v2/server/`` API on behalf of another server and sign the @@ -95,7 +95,7 @@ server by querying other servers. Publishing Keys ^^^^^^^^^^^^^^^ -Home servers publish the allowed TLS fingerprints and signing keys in a JSON +Homeservers publish the allowed TLS fingerprints and signing keys in a JSON object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of ``verify_keys`` that are valid for signing federation requests made by the server and for signing events. It contains a list of ``old_verify_keys`` @@ -114,7 +114,7 @@ certificate currently in use by the server. These fingerprints are valid until the millisecond POSIX timestamp in ``valid_until_ts``. The ``verify_keys`` can be used to sign requests and events made by the server -until the millisecond POSIX timestamp in ``valid_until_ts``. If a Home Server +until the millisecond POSIX timestamp in ``valid_until_ts``. If a homeserver receives an event with a ``origin_server_ts`` after the ``valid_until_ts`` then it should request that ``key_id`` for the originating server to check whether the key has expired. @@ -136,8 +136,8 @@ events sent by that server can still be checked. ==================== =================== ====================================== Key Type Description ==================== =================== ====================================== -``server_name`` String DNS name of the home server. -``verify_keys`` Object Public keys of the home server for +``server_name`` String DNS name of the homeserver. +``verify_keys`` Object Public keys of the homeserver for verifying digital signatures. ``old_verify_keys`` Object The public keys that the server used to use and when it stopped using them. @@ -238,14 +238,14 @@ Version 1 Version 1 of key distribution is obsolete -Home servers publish their TLS certificates and signing keys in a JSON object +Homeservers publish their TLS certificates and signing keys in a JSON object at ``/_matrix/key/v1``. ==================== =================== ====================================== Key Type Description ==================== =================== ====================================== -``server_name`` String DNS name of the home server. -``verify_keys`` Object Public keys of the home server for +``server_name`` String DNS name of the homeserver. +``verify_keys`` Object Public keys of the homeserver for verifying digital signatures. ``signatures`` Object Digital signatures for this object signed using the ``verify_keys``. @@ -278,9 +278,9 @@ Transactions .. WARNING:: This section may be misleading or inaccurate. -The transfer of EDUs and PDUs between home servers is performed by an exchange +The transfer of EDUs and PDUs between homeservers is performed by an exchange of Transaction messages, which are encoded as JSON objects, passed over an HTTP -PUT request. A Transaction is meaningful only to the pair of home servers that +PUT request. A Transaction is meaningful only to the pair of homeservers that exchanged it; they are not globally-meaningful. Each transaction has: @@ -445,7 +445,7 @@ EDUs EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of "previous" IDs. The only mandatory fields for these are the type, origin and -destination home server names, and the actual nested content. +destination homeserver names, and the actual nested content. ======================== ============ ========================================= Key Type Description @@ -531,7 +531,7 @@ To make a query:: Query args: as specified by the individual query types Response: JSON encoding of a response object -Performs a single query request on the receiving home server. The Query Type +Performs a single query request on the receiving homeserver. The Query Type part of the path specifies the kind of query being made, and its query arguments have a meaning specific to that kind of query. The response is a JSON-encoded object whose meaning also depends on the kind of query. @@ -791,9 +791,9 @@ because HTTP services like Matrix are often deployed behind load balancers that handle the TLS and these load balancers make it difficult to check TLS client certificates. -A home server may provide a TLS client certificate and the receiving home server +A homeserver may provide a TLS client certificate and the receiving homeserver may check that the client certificate matches the certificate of the origin -home server. +homeserver. Server-Server Authorization --------------------------- @@ -905,7 +905,7 @@ Querying profile information:: If the query contains the optional ``field`` key, it should give the name of a result field. If such is present, then the result should contain only a field of that name, with no others present. If not, the result should contain as much -of the user's profile as the home server has available and can make public. +of the user's profile as the homeserver has available and can make public. Directory --------- diff --git a/supporting-docs/examples/application-services.rst b/supporting-docs/examples/application-services.rst index bde4531b..fae3613d 100644 --- a/supporting-docs/examples/application-services.rst +++ b/supporting-docs/examples/application-services.rst @@ -6,15 +6,15 @@ This file contains examples of some application service IRC Bridge ---------- Pre-conditions: - - Server admin stores the AS token "T_a" on the home server. - - Home server has a token "T_h". - - Home server has the domain "hsdomain.com" + - Server admin stores the AS token "T_a" on the homeserver. + - Homeserver has a token "T_h". + - Homeserver has the domain "hsdomain.com" 1. Application service registration :: - AS -> HS: Registers itself with the home server + AS -> HS: Registers itself with the homeserver POST /register { url: "https://someapp.com/matrix", diff --git a/supporting-docs/guides/2015-08-10-client-server.rst b/supporting-docs/guides/2015-08-10-client-server.rst index 2800584c..fe6b464a 100644 --- a/supporting-docs/guides/2015-08-10-client-server.rst +++ b/supporting-docs/guides/2015-08-10-client-server.rst @@ -19,11 +19,11 @@ How to use the client-server API The git version of this document is {% project_version %} This guide focuses on how the client-server APIs *provided by the reference -home server* can be used. Since this is specific to a home server +homeserver* can be used. Since this is specific to a homeserver implementation, there may be variations in relation to registering/logging in which are not covered in extensive detail in this guide. -If you haven't already, get a home server up and running on +If you haven't already, get a homeserver up and running on ``http://localhost:8008``. @@ -56,8 +56,8 @@ if you forget the ``access_token``. Implementation note: The matrix specification does not enforce how users register with a server. It just specifies the URL path and absolute minimum -keys. The reference home server uses a username/password to authenticate user, -but other home servers may use different methods. This is why you need to +keys. The reference homeserver uses a username/password to authenticate user, +but other homeservers may use different methods. This is why you need to specify the ``type`` of method. Login @@ -82,13 +82,13 @@ The aim when logging in is to get an access token for your existing user ID:: "user_id": "@example:localhost" } -Implementation note: Different home servers may implement different methods for +Implementation note: Different homeservers may implement different methods for logging in to an existing account. In order to check that you know how to login -to this home server, you must perform a ``GET`` first and make sure you +to this homeserver, you must perform a ``GET`` first and make sure you recognise the login type. If you do not know how to login, you can ``GET /login/fallback`` which will return a basic webpage which you can use to -login. The reference home server implementation support username/password login, -but other home servers may support different login methods (e.g. OAuth2). +login. The reference homeserver implementation support username/password login, +but other homeservers may support different login methods (e.g. OAuth2). Communicating diff --git a/supporting-docs/guides/2015-08-21-application_services.md b/supporting-docs/guides/2015-08-21-application_services.md index dd532d42..e034e154 100644 --- a/supporting-docs/guides/2015-08-21-application_services.md +++ b/supporting-docs/guides/2015-08-21-application_services.md @@ -6,7 +6,7 @@ categories: guides # Application services -Application services are distinct modules which which sit alongside a home server providing arbitrary extensible functionality decoupled from the home server implementation. Just like the rest of Matrix, they communicate via HTTP using JSON. Application services function in a very similar way to traditional clients, but they are given much more power than a normal client. They can reserve entire namespaces of room aliases and user IDs for their own purposes. They can silently monitor events in rooms, or any events directed at any user ID. This power allows application services to have extremely useful abilities which overall enhance the end user experience. +Application services are distinct modules which which sit alongside a homeserver providing arbitrary extensible functionality decoupled from the homeserver implementation. Just like the rest of Matrix, they communicate via HTTP using JSON. Application services function in a very similar way to traditional clients, but they are given much more power than a normal client. They can reserve entire namespaces of room aliases and user IDs for their own purposes. They can silently monitor events in rooms, or any events directed at any user ID. This power allows application services to have extremely useful abilities which overall enhance the end user experience. | @@ -47,17 +47,17 @@ At present, the IRC application service is in beta, and is being run on #matrix | # What Application services can do for you -Application services have enormous potential for creating new and exciting ways to transform and enhance the core Matrix protocol. For example, you could aggregate information from multiple rooms into a summary room, or create throwaway virtual user accounts to proxy messages for a fixed user ID on-the-fly. As you may expect, all of this power assumes a high degree of trust between application services and home servers. Only home server admins can allow an application service to link up with their home server, and the application service is in no way federated to other home servers. You can think of application services as additional logic on the home server itself, without messing around with the book-keeping that home servers have to do. This makes adding useful functionality very easy. +Application services have enormous potential for creating new and exciting ways to transform and enhance the core Matrix protocol. For example, you could aggregate information from multiple rooms into a summary room, or create throwaway virtual user accounts to proxy messages for a fixed user ID on-the-fly. As you may expect, all of this power assumes a high degree of trust between application services and homeservers. Only homeserver admins can allow an application service to link up with their homeserver, and the application service is in no way federated to other homeservers. You can think of application services as additional logic on the homeserver itself, without messing around with the book-keeping that homeservers have to do. This makes adding useful functionality very easy. | ### Example -The application service (AS) API itself uses webhooks to communicate from the home server to the AS: +The application service (AS) API itself uses webhooks to communicate from the homeserver to the AS: -- Room Alias Query API : The home server hits a URL on your application server to see if a room alias exists. -- User Query API : The home server hits a URL on your application server to see if a user ID exists. -- Push API : The home server hits a URL on your application server to notify you of new events for your users and rooms. +- Room Alias Query API : The homeserver hits a URL on your application server to see if a room alias exists. +- User Query API : The homeserver hits a URL on your application server to see if a user ID exists. +- Push API : The homeserver hits a URL on your application server to notify you of new events for your users and rooms. A very basic application service may want to log all messages in rooms which have an alias starting with "#logged_" (side note: logging won't work if these rooms are using end-to-end encryption). @@ -85,7 +85,7 @@ Set your new application service running on port 5000 with: python app_service.py -The home server needs to know that the application service exists before it will send requests to it. This is done via a registration YAML file which is specified in Synapse's main config file e.g. homeserver.yaml. The server admin needs to add the application service registration configuration file as an entry to this file. +The homeserver needs to know that the application service exists before it will send requests to it. This is done via a registration YAML file which is specified in Synapse's main config file e.g. homeserver.yaml. The server admin needs to add the application service registration configuration file as an entry to this file. # homeserver.yaml app_service_config_files: @@ -115,7 +115,7 @@ NB: Note the "-" at the start; this indicates a list element. The registration f - exclusive: false regex: "#logged_.*" -**You will need to restart the home server after editing the config file before it will take effect.** +**You will need to restart the homeserver after editing the config file before it will take effect.** | @@ -138,6 +138,6 @@ This makes the application service lazily create a room with the requested alias | -Application services are powerful components which extend the functionality of home servers, but they are limited. They can only ever function in a "passive" way. For example, you cannot implement an application service which censors swear words in rooms, because there is no way to prevent the event from being sent. Aside from the fact that censoring will not work when using end-to-end encryption, all federated home servers would also need to reject the event in order to stop developing an inconsistent event graph. To "actively" monitor events, another component called a "Policy Server" is required, which is beyond the scope of this post.  Also, Application Services can result in a performance bottleneck, as all events on the homeserver must be ordered and sent to the registered application services.  If you are bridging huge amounts of traffic, you may be better off having your bridge directly talk the Server-Server federation API rather than the simpler Application Service API. +Application services are powerful components which extend the functionality of homeservers, but they are limited. They can only ever function in a "passive" way. For example, you cannot implement an application service which censors swear words in rooms, because there is no way to prevent the event from being sent. Aside from the fact that censoring will not work when using end-to-end encryption, all federated homeservers would also need to reject the event in order to stop developing an inconsistent event graph. To "actively" monitor events, another component called a "Policy Server" is required, which is beyond the scope of this post.  Also, Application Services can result in a performance bottleneck, as all events on the homeserver must be ordered and sent to the registered application services.  If you are bridging huge amounts of traffic, you may be better off having your bridge directly talk the Server-Server federation API rather than the simpler Application Service API. I hope this demonstrates how easy it is to create an application service, along with a few ideas of the kinds of things you can do with them. Obvious uses include build protocol bridges, search engines, invisible bots, etc. For more information on the AS HTTP API, check out the new Application Service API section in the spec, or the raw drafts and spec in https://github.com/matrix-org/matrix-doc/. diff --git a/supporting-docs/howtos/client-server.rst b/supporting-docs/howtos/client-server.rst index 3bed5a9f..e5a85d41 100644 --- a/supporting-docs/howtos/client-server.rst +++ b/supporting-docs/howtos/client-server.rst @@ -11,11 +11,11 @@ How to use the client-server API The git version of this document is ``{{git_version}}`` This guide focuses on how the client-server APIs *provided by the reference -home server* can be used. Since this is specific to a home server +homeserver* can be used. Since this is specific to a homeserver implementation, there may be variations in relation to registering/logging in which are not covered in extensive detail in this guide. -If you haven't already, get a home server up and running on +If you haven't already, get a homeserver up and running on ``http://localhost:8008``. @@ -48,8 +48,8 @@ if you forget the ``access_token``. Implementation note: The matrix specification does not enforce how users register with a server. It just specifies the URL path and absolute minimum -keys. The reference home server uses a username/password to authenticate user, -but other home servers may use different methods. This is why you need to +keys. The reference homeserver uses a username/password to authenticate user, +but other homeservers may use different methods. This is why you need to specify the ``type`` of method. Login @@ -74,13 +74,13 @@ The aim when logging in is to get an access token for your existing user ID:: "user_id": "@example:localhost" } -Implementation note: Different home servers may implement different methods for +Implementation note: Different homeservers may implement different methods for logging in to an existing account. In order to check that you know how to login -to this home server, you must perform a ``GET`` first and make sure you +to this homeserver, you must perform a ``GET`` first and make sure you recognise the login type. If you do not know how to login, you can ``GET /login/fallback`` which will return a basic webpage which you can use to -login. The reference home server implementation support username/password login, -but other home servers may support different login methods (e.g. OAuth2). +login. The reference homeserver implementation support username/password login, +but other homeservers may support different login methods (e.g. OAuth2). Communicating diff --git a/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.html b/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.html index 088ff7ac..b7e874c2 100644 --- a/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.html +++ b/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.html @@ -1,5 +1,5 @@
-

This room creation / message sending demo requires a home server to be running on http://localhost:8008

+

This room creation / message sending demo requires a homeserver to be running on http://localhost:8008

diff --git a/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.js b/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.js index 9c346e2f..c16395ac 100644 --- a/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.js +++ b/supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.js @@ -19,7 +19,7 @@ $('.login').live('click', function() { showLoggedIn(data); }, error: function(err) { - var errMsg = "To try this, you need a home server running!"; + var errMsg = "To try this, you need a homeserver running!"; var errJson = $.parseJSON(err.responseText); if (errJson) { errMsg = JSON.stringify(errJson); diff --git a/supporting-docs/howtos/jsfiddles/event_stream/demo.html b/supporting-docs/howtos/jsfiddles/event_stream/demo.html index 7657780d..3de7b081 100644 --- a/supporting-docs/howtos/jsfiddles/event_stream/demo.html +++ b/supporting-docs/howtos/jsfiddles/event_stream/demo.html @@ -1,5 +1,5 @@
-

This event stream demo requires a home server to be running on http://localhost:8008

+

This event stream demo requires a homeserver to be running on http://localhost:8008

diff --git a/supporting-docs/howtos/jsfiddles/event_stream/demo.js b/supporting-docs/howtos/jsfiddles/event_stream/demo.js index acba8391..65b118d2 100644 --- a/supporting-docs/howtos/jsfiddles/event_stream/demo.js +++ b/supporting-docs/howtos/jsfiddles/event_stream/demo.js @@ -58,7 +58,7 @@ $('.login').live('click', function() { showLoggedIn(data); }, error: function(err) { - var errMsg = "To try this, you need a home server running!"; + var errMsg = "To try this, you need a homeserver running!"; var errJson = $.parseJSON(err.responseText); if (errJson) { errMsg = JSON.stringify(errJson); diff --git a/supporting-docs/howtos/jsfiddles/example_app/demo.html b/supporting-docs/howtos/jsfiddles/example_app/demo.html index 7a9dffdd..a183f61d 100644 --- a/supporting-docs/howtos/jsfiddles/example_app/demo.html +++ b/supporting-docs/howtos/jsfiddles/example_app/demo.html @@ -1,5 +1,5 @@