Repository files navigation

Hasura storage is a service that adds a storage service on top of hasura and any s3-compatible storage service. The goal is to be able to leverage the cloud storage service while also leveraging hasura features like its graphql API, permissions, actions, presets, etc...

To understand what hasura-storage does we can look at the two main workflows to upload and retrieve files.

When a user wants to upload a file hasura-storage will first check with hasura if the user is allowed to do so, if it the file will be uploaded to s3 and, on completion, file metadata will be stored in hasura.

sequenceDiagram    actor User    autonumber    User->>+hasura-storage: upload file    hasura-storage->>+hasura: check permissions    hasura->>-hasura-storage: return if user can upload file    hasura-storage->>+s3: upload file    s3->>-hasura-storage: file information    hasura-storage->>+hasura: file metadata    hasura->>-hasura-storage: success    hasura-storage->>-User: file metadata

Similarly, when retrieving files, hasura-storage will first check with hasura if the user has permissions to retrieve the file and if the user is allowed, it will forward the file to the user:

sequenceDiagram    actor User    autonumber    User->>+hasura-storage: request file    hasura-storage->>+hasura: check permissions    hasura->>-hasura-storage: return if user can access file    hasura-storage->>+s3: request file    s3->>-hasura-storage: file    hasura-storage->>-User: file

The main features of the service are:

• leverage hasura's permissions to allow users to upload/retrieve files
• upload files to any s3-compatible service
• download files from any s3-compatible service
• create presigned URLs to grant temporary access
• caching information to integrate with caches and CDNs (cache headers, etag, conditional headers, etc)
• perform basic image manipulation on the fly
• integration withclamav antivirus

Integration withclamav antivirus relies on an externalclamd service. When a file is uploadedhasura-storage will create the file metadata first and then check if the file is clean withclamd via its TCP socket. If the file is clean the rest of the process will continue as usual. If a virus is found details about the virus will be added to thevirus table and the rest of the process will be aborted.

sequenceDiagram    actor User    User ->> storage: upload file    storage ->>clamav: check for virus    alt virus found        storage-->s3: abort upload        storage->>graphql: insert row in virus table    else virus not found        storage->>s3: upload        storage->>graphql: update metadata    end

This feature can be enabled with the flag--clamav-server string, wherestring is the tcp address for the clamd service.

The service comes with anOpenAPI definition which you can also seeonline.

Easiest way to get started is by usingnhost's free tier but if you want to self-host you can easily do it yourself as well.

Requirements:

1. hasura running, which in turns needspostgres or any other supported database.
2. An s3-compatible service. For instance,AWS S3,minio, etc...

A fully working example using docker-compose can be foundhere. Just remember to replace the imagehasura-storage:dev with a validdocker image, for instance,nhost/hasura-storage:0.1.5.

If you need help or want to contribute it is recommended to read thecontributing information first. In addition, if you plan to contribute with code it is also encouraged to read thedevelopment guide.