Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

General/small improvements to the application service API specification #1533

Merged
merged 4 commits into from
Aug 20, 2018
Merged

General/small improvements to the application service API specification #1533

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5b5b4cf
Explicitly say how appservices should detect state events
turt2live Aug 17, 2018
fd101b6
Misc language changes
turt2live Aug 17, 2018
7caad61
Clearly state how the users namespace relates to interest in events
turt2live Aug 17, 2018
c8ba2e0
Wording improvements for appservices
turt2live Aug 20, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion api/application-service/application_service.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ paths:
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.

The application service should take care to ensure that it handles
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/handles/detects/

or 'Note that the application service should distinguish state events from message events via the presence of a state_key, rather than via the event type."

state events by the presence of a ``state_key``, not by the event
type.
operationId: sendTransaction
parameters:
- in: path
Expand All @@ -44,7 +48,7 @@ paths:
x-example: "35"
- in: body
name: body
description: A list of events
description: A list of events.
schema:
type: object
example: {
Expand Down
14 changes: 11 additions & 3 deletions specification/application_service_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.. Copyright 2016 OpenMarket Ltd
.. Copyright 2018 New Vector Ltd
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -39,7 +40,7 @@ This version of the specification is generated from
Application Services
--------------------
Application services are passive and can only observe events from a given
homeserver. They can inject events into rooms they are participating in.
homeserver (HS). They can inject events into rooms they are participating in.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd kinda rather we just used 'homeserver' throughout. But I don't mind overmuch if you don't want to do that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also rather "homeserver", however the diff becomes insane because "HS" is used everywhere, pushing the line length all out of whack. Kinda settled for this pending something to take out the acronyms from everywhere as one giant "fix the world" PR or something.

They cannot prevent events from being sent, nor can they modify the content of
the event being sent. In order to observe events from a homeserver, the
homeserver needs to be configured to pass certain types of traffic to the
Expand Down Expand Up @@ -68,7 +69,13 @@ Registration
Application services register "namespaces" of user IDs, room aliases and room IDs.
These namespaces are represented as regular expressions. An application service
is said to be "interested" in a given event if one of the IDs in the event match
the regular expression provided by the application service. An application
the regular expression provided by the application service, such as the room having
an alias or ID in the relevant namespaces. Similarly, the application service is
said to be interested in a given event if one of the application service's namespaced
users is the target of the event, or is a joined member of the room where the event
occurred.

An application
service can also state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive"
namespace. An exclusive namespace prevents humans and other application
Expand Down Expand Up @@ -217,7 +224,8 @@ need to be able to adjust the ``origin_server_ts`` value to do this.

Inputs:
- Application service token (``as_token``)
- Desired timestamp
- Desired timestamp in milliseconds since the unix epoch
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggest using parens: "Desired timestamp (in milliseconds since the unix epoch)."

(Aside: should we just have a note in the introduction that all timestamps are in ms since the epoch, and then just use 'timestamp' throughout the rest of the spec?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's #1468 that kinda covers the case of "wtf is a timestamp". Putting it in the intro seems much better than going through the entire spec looking for "timestamp".


Notes:
- This will only apply when sending events.

Expand Down