From a4aea5337fe6b93e55f9dae1974ead962c1997e8 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Sun, 8 May 2022 21:31:29 -0300 Subject: [PATCH] sneak filter.limit in nip-01. --- 01.md | 9 ++++++--- 05.md | 6 +++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/01.md b/01.md index 39aac0e0..8b818282 100644 --- a/01.md +++ b/01.md @@ -4,7 +4,7 @@ NIP-01 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. @@ -62,16 +62,17 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th ``` { "ids": , + "authors": , "kinds": , "#e": , "#p": , "since": , "until": , - "authors": + "limit": } ``` -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 `` or a new `REQ` is sent using the same ``, 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 `` or a new `REQ` is sent using the same ``, 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. @@ -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. +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 Relays can send 2 types of messages, which must also be JSON arrays, according to the following patterns: diff --git a/05.md b/05.md index 32679606..1741aae4 100644 --- a/05.md +++ b/05.md @@ -51,15 +51,15 @@ Clients may treat the identifier `_@domain` as the "root" identifier, and choose By adding the `` 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 $ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep ^Access-Control 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