The Pods library provides a way for a pico in the Pico Engine to access Solid Pod storage for persistent, interchangeable storage. The user must manually create storage (you can use a provider at https://solidproject.org/users/get-a-pod or you can use host a Solid server on your local machine at https://github.com/CommunitySolidServer/CommunitySolidServer ) and use a provided pico action to connect the storage to the pico.

The library supports adding, retrieving (without deleting), copying (without deleting), listing of, and deleting of files from the pod. The library also supports the creation and deletion of containers (referred to as folders in naming) and the modification of access permissions.

Future Notes/Plans:

• Currently, the library does not check for or use relative URLs. This could be an additional feature implemented in the future.

• Currently, the library has no way to programmatically manipulate storage creation/deletion inside a Solid server, due to using Inrupt’s Javascript API which does not have methods for creating/deleting storage. Inrupt has mentioned they plan to implement this feature in the future, which would then allow this library to also create and delete storage inside a Solid server after some modification.

• Currently, the pods:store() and pods:overwrite() functions have a size limit for the originURL parameter when using a data scheme as input.

• Currently, a pico and storage exist in a Many-to-1 relationship (or Many-to-0 relationship) as any number of picos may connect to a single storage. In the future, the library could be expanded to include picos connected to multiple Solid storages.

• We had a plan to create a function that would take in the name of any command in Inrupt’s Javascript client library and then call that function. We did not have time to implement this function, but it may be useful to implement this in the future.

• A small implementation note: automatic authentication is currently implemented with a lot of duplicate code. We would have preferred to use the template pattern to do this, but we ran out of time. This may be something to implement for future improvements to the module.

• File names are currently acquired by splitting the destination URL at the last slash and taking the right portion of that split. This unfortunately includes any query parameters in the URL which can cause issues and needs cleaning.

• Resource access management needs expansion (functionality to look at a specific agent’s permissions, and functionality to look at a specific agent’s/the public’s permissions individually).

• Documentation is assuming your web ID (identified via client ID and client secret) has the appropriate access permissions on the Solid server.

Pod Terminology

Solid has its own terminology, some of which has been adopted into this library.

• Storage: refers to the actual storage space where files reside.

  • For the purposes of this document, “pod” and “storage” are rather interchangeable. We have chosen to use the word “storage” in the library because of discrepancies between the two that are beyond the scope of this document.

• Container: analogous to a folder or a directory in the file system. Can be empty or can contain files and/or subcontainers. Pod URLs access the root container by default.

  • We have chosen to use the word “folder” instead of “container” in the library, as seen in actions like “createFolder” and “removeFolder.” We did this because we believe that the word “folder” is more intuitive for most users.

Automation

The following are automatically performed whenever a function or action from the library is called, unless specified via an optional parameter.

• Authentication: Once authentication information is passed in via the connect_storage action, each function/action called from the library will automatically check whether the authentication remains valid and attempt to authenticate the pico once. The user may disable automatic authentication attempts if they so choose by passing in an optional parameter. Additionally, each function/action will check whether the specific process is authorized (e.g. if the user is requesting a file that denies all read access).

Documentation