sneak filter.limit in nip-01.

This commit is contained in:
fiatjaf 2022-05-08 21:31:29 -03:00
parent 57b86d2482
commit a4aea5337f
2 changed files with 9 additions and 6 deletions

9
01.md
View File

@ -4,7 +4,7 @@ NIP-01
Basic protocol flow description Basic protocol flow description
------------------------------- -------------------------------
`draft` `mandatory` `author:fiatjaf` `author:distbit` `author:scsibug` `author:kukks` `draft` `mandatory` `author:fiatjaf` `author:distbit` `author:scsibug` `author:kukks` `author:jb55`
This NIP defines the basic protocol that should be implemented by everybody. New NIPs may add new optional (or mandatory) fields and messages and features to the structures and flows described here. This NIP defines the basic protocol that should be implemented by everybody. New NIPs may add new optional (or mandatory) fields and messages and features to the structures and flows described here.
@ -62,16 +62,17 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th
``` ```
{ {
"ids": <a list of event ids or prefixes>, "ids": <a list of event ids or prefixes>,
"authors": <a list of pubkeys or prefixes, the pubkey of an event must be one of these>,
"kinds": <a list of a kind numbers>, "kinds": <a list of a kind numbers>,
"#e": <a list of event ids that are referenced in an "e" tag>, "#e": <a list of event ids that are referenced in an "e" tag>,
"#p": <a list of pubkeys that are referenced in a "p" tag>, "#p": <a list of pubkeys that are referenced in a "p" tag>,
"since": <a timestamp, events must be newer than this to pass>, "since": <a timestamp, events must be newer than this to pass>,
"until": <a timestamp, events must be older than this to pass>, "until": <a timestamp, events must be older than this to pass>,
"authors": <a list of pubkeys or prefixes, the pubkey of an event must be one of these> "limit": <maximum number of events to be returned in the initial query>
} }
``` ```
Upon receiving a `REQ` message, the relay MUST query its internal database and return events that match the filter, then store that filter and send again all future events it receives to that same websocket until the websocket is closed. The `CLOSE` event is received with the same `<subscription_id>` or a new `REQ` is sent using the same `<subscription_id>`, in which case it should overwrite the previous subscription. Upon receiving a `REQ` message, the relay SHOULD query its internal database and return events that match the filter, then store that filter and send again all future events it receives to that same websocket until the websocket is closed. The `CLOSE` event is received with the same `<subscription_id>` or a new `REQ` is sent using the same `<subscription_id>`, in which case it should overwrite the previous subscription.
Filter attributes containing lists (such as `ids`, `kinds`, or `#e`) are JSON arrays with one or more values. At least one of the array's values must match the relevant field in an event for the condition itself to be considered a match. For scalar event attributes such as `kind`, the attribute from the event must be contained in the filter list. For tag attributes such as `#e`, where an event may have multiple values, the event and filter condition values must have at least one item in common. Filter attributes containing lists (such as `ids`, `kinds`, or `#e`) are JSON arrays with one or more values. At least one of the array's values must match the relevant field in an event for the condition itself to be considered a match. For scalar event attributes such as `kind`, the attribute from the event must be contained in the filter list. For tag attributes such as `#e`, where an event may have multiple values, the event and filter condition values must have at least one item in common.
@ -81,6 +82,8 @@ All conditions of a filter that are specified must match for an event for it to
A `REQ` message may contain multiple filters. In this case events that match any of the filters are to be returned, i.e., multiple filters are to be interpreted as `||` conditions. A `REQ` message may contain multiple filters. In this case events that match any of the filters are to be returned, i.e., multiple filters are to be interpreted as `||` conditions.
The `limit` property of a filter is only valid for the initial query and can be ignored afterwards. When `limit: n` is present it is assumed that the the events returned in the initial query will be the latest `n` events. It is safe to return less events than `limit` specifies, but it is expected that relays do not return (much) more events than requested so clients don't get unnecessarily overwhelmed by data.
### From relay to client: sending events and notices ### From relay to client: sending events and notices
Relays can send 2 types of messages, which must also be JSON arrays, according to the following patterns: Relays can send 2 types of messages, which must also be JSON arrays, according to the following patterns:

6
05.md
View File

@ -51,15 +51,15 @@ Clients may treat the identifier `_@domain` as the "root" identifier, and choose
By adding the `<local-part>` as a query string instead of as part of the path the protocol can support both dynamic servers that can generate JSON on-demand and static servers with a JSON file in it that may contain multiple names. By adding the `<local-part>` as a query string instead of as part of the path the protocol can support both dynamic servers that can generate JSON on-demand and static servers with a JSON file in it that may contain multiple names.
### Allowing access from Javascript apps ### Allowing access from JavaScript apps
Javascript Nostr apps may be restricted by browser [CORS][] policies that prevent them from accesing `nostr.json` on the user's domain. When CORS prevents JS from loading a resource, the JS program sees it as a network failure identical to the resource not existing, so it is not possible for a pure-JS app to tell the user for certain that the failure was caused by a CORS issue. JS Nostr apps that see network failures requesting `nostr.json` files may want to recommend to users that they check the CORS policy of their servers, e.g.: JavaScript Nostr apps may be restricted by browser [CORS][] policies that prevent them from accesing `/.well-known/nostr.json` on the user's domain. When CORS prevents JS from loading a resource, the JS program sees it as a network failure identical to the resource not existing, so it is not possible for a pure-JS app to tell the user for certain that the failure was caused by a CORS issue. JS Nostr apps that see network failures requesting `/.well-known/nostr.json` files may want to recommend to users that they check the CORS policy of their servers, e.g.:
```bash ```bash
$ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep ^Access-Control $ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep ^Access-Control
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
``` ```
Users should ensure that their `nostr.json` is served with the HTTP header `Access-Control-Allow-Origin: *` to ensure it can be validated by pure JS apps running in modern browsers. Users should ensure that their `/.well-known/nostr.json` is served with the HTTP header `Access-Control-Allow-Origin: *` to ensure it can be validated by pure JS apps running in modern browsers.
[CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS [CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS