Document the batched title lookup: POST /items/titles, marfa items titles, and the refused-lookup notice #824

What changed

withmarfa/marfa#2630 changes how a folder resolves the names in its links. It also adds a server endpoint and a command.

• New endpoint: POST /items/titles. It takes up to 200 names and returns, for each name, the items whose title equals that name. The match ignores case and Unicode form. Each name returns at most 20 items, with more set when there are others. A key sees only the items it could list through GET /items. A title longer than 1,000 UTF-16 code units matches no name.
• New command: marfa items titles. It calls the endpoint from the command line.
• Fewer requests from folders. A folder now sends the names in its links to the server in batches, not one name at a time. It doesn't ask the server about a name its own copy already holds under two items, because that name is ambiguous whatever the server holds.
• A new notice. When a server refuses the title lookup as a whole (for example, an older server without the endpoint), folders scan, push and watch say so once. Linked files wait, and the folder asks again on the next scan, so files don't have to be edited to retry. A watch repeats the notice only when it changes. Apps see the same notice as lookup_refused on a folder scan in the Swift and Node bindings.

Why

A first sync of a large notes folder into a large instance spent most of its time looking up link names one at a time, and used up the server's rate limit.

Who it's for

• People who sync a notes folder.
• App and SDK developers who read a folder's scan.
• Anyone who reads the API reference.

Pages

The API reference for items, the marfa items command reference, and the folder sync pages that cover how links are resolved and what the watch reports.

Release

The next Marfa release after v0.0.58.