Something outside the View reads as not found

​

Signs

• A read by ID of a File, a version or a collection fails with file_not_found, resource_unavailable, route_not_found or collection_not_found. The person says the item exists, and a person with full access can read it.
• A read of an entity or relationship by ID fails with not_found.
• A list or a search returns fewer items than the person expects. A search filter that names a File or collection outside the View finds nothing.
• A walk of the Graph misses entities that you know exist, or a relationship has vanished.
• penumbra access me prints “You read only the View”, with a name.

​

Why it happens

A View hides what lies outside it. If an outside item answered “forbidden”, a client could learn that the item exists, how many there are, and what they are called. So an outside item answers exactly as an item that does not exist. Your credential is limited to a View, and the item is not in it. Two parts of the View are easy to miss. A View that names collections shows a File only while it is in one of them. In the default graph mode, an entity is hidden when every File that it cites lies outside the View.

​

What Penumbra does

By itself:

• Answers a read by ID of a File, version or collection outside the View as it answers one that does not exist.
• Answers a read of an entity or relationship that the View hides with not_found, and shows no citations for it.
• Hides a relationship when either of its two entities is hidden.
• In the default graph mode, shows an entity only if it has no File citations or one inside the View, when the View limits Files.
• Removes citations to Files outside the View from the entities it shows, in both graph modes.
• Returns only the collections and Files inside the View, and returns no tags.
• Reads the members of an included collection when someone reads, so adding a File to it shows the File at once.

You must:

• Run penumbra access me before you decide that an item does not exist.
• Tell the person that the item is not visible to this credential, and never that it is missing.
• Ask a person who manages access, or use a credential with no View, to read the item.

Not handled:

• Penumbra does not tell a limited credential that an item exists outside its View, or how many items are hidden.
• The CLI hints for file_not_found and resource_unavailable do not mention a View limit.
• penumbra status does not show a View limit, so a limited credential looks like a viewer with a small project.

​

Do

1. Run penumbra access me with the credential that missed the item. If it prints “You read the whole project”, this entry does not apply. Use problem search-returns-nothing.
2. Say to the person that the credential reads only the View, and name it.
3. Find out whether the item should be inside. A person who manages access runs penumbra context slice show <view-id>, then penumbra files collections files <collection> for each included collection.
4. If a File should be inside, add it to an included collection: penumbra files collections add <collection> <file>. It appears at once. Decide first that everyone limited to the View may read it (card rule collection.9).
5. If an entity should be inside, find the Files that it cites. In the default graph mode, it shows when one of them is inside. Otherwise add one, or attach the limit again with --graph-mode types if the person accepts what that shows (card rule view.5).
6. If a type should be inside, the View needs a new publish (problem view-needs-republish).
7. If the item should stay hidden, tell the person that it is outside the View, and stop.

​

Don’t

• Don’t say that the File or entity does not exist. It exists, and your credential cannot see it.
• Don’t upload the document again to make it visible. The copy is a second File, and it does not fix the cause.
• Don’t remove the limit with penumbra access remove to look. The key, agent or login then reads the whole project.
• Don’t use the counts of a limited credential as totals. They count what the View shows and nothing else.

​

Check

• The limited credential reads the item by its ID, or the person agrees that it stays hidden.
• penumbra access receipts <limit-id> lists the read, as a person who manages access. Take <limit-id> from penumbra access list.

​

Related

Card view, with rules view.3, view.5 and view.15. Card credential. Problems view-needs-republish and search-returns-nothing. Recipe share-with-a-view.

​

Keep going

View · Credential · Collection · Search returns nothing · A new File is not searchable yet · A View does not follow a Shape change until it is published again · Share part of a project with a View