Skip to content

Latest commit

 

History

History
175 lines (142 loc) · 5.72 KB

sharing.md

File metadata and controls

175 lines (142 loc) · 5.72 KB

Document Sharing in DocFlow

Let's see how sharing happens in Docflow. 🚀

For sharing DocFlow has 3-endpoints:

  1. Share Document Link: Share document as a link.
  2. Redirect To Share: Redirects the shared link to the document.
  3. Share Document: Shares document.

Share Document Link

  • 🎯 Endpoint: POST /v2/share-link/:document
  • ⚙️ Params: Path Params=document
  • 📦 Payload: { "visits": 1, "share_to": [ "" ] }
  • 🔐 Authorization: Bearer <token>

➰ cURL:

curl --location 'localhost:8000/v2/share-link/:document' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "visits": 1,
  "share_to": [
    ""
  ]
}'

Let's see how this endpoint works, the code for the following endpoint is on app/api/routes/document_sharing.py under share_link_document().

It takes in the following arguments...

document (Union[str, UUID]): The ID or name of the document to be shared.
share_request (SharingRequest): The sharing request containing the details of the sharing operation.
repository (DocumentSharingRepository): The repository for managing document sharing.
auth_repository (AuthRepository): The repository for managing User related queries.
metadata_repository (DocumentMetadataRepository): The repository for managing document metadata.
notify_repository (NotifyRepo): The repository for managing notification
user (TokenData): The token data of the authenticated user.

And returns:

{
    "personal_url": "<pre_signed_url>",
    "share_this": "<shareable_link>"
}

So when we share a document by link, the shared email/username should hold an account on docflow (share_to); also we limit the link's usage with visits.

personal_url, which is noting but a pre_signed_url, which gets generated by aws. and share_this, which is a shareable link, generates a link as /api/doc/<url_id> which has fixed number of visits and can only be accessed by users, specified by owner of the file with share_to. This shared url acts as shortened url to access the document, in a controlled manner.

Now this share_this link can be accessed with the second endpoint, Redirect to share.

Redirect to Share

  • 🎯 Endpoint: POST /v2/doc/:url_id
  • ⚙️ Params: Path Params=url_id
  • 🔐 Authorization: Bearer <token>

➰ cURL:

curl --location 'localhost:8000/v2/doc/:url_id' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

The code for the following endpoint is on app/api/routes/document_sharing.py. called redirect_to_share(). It takes in the following arguments

url_id (str): The ID of the shared document URL.
repository (DocumentSharingRepository): The repository for managing document sharing.
user (TokenData): The token data of the authenticated user.

And returns:

A RedirectResponse() to a file, which downloads the document.

Now when the user tries to access the endpoint with the valid url_id, the user is able to download the file. As the number of clicks reaches the limit visits, the link is no longer valid.

Share Document

  • 🎯 Endpoint: POST /v2/share/document?document=&notify=true
  • ⚙️ Params: document: <str> notify:true
  • 🔐 Authorization: Bearer <token>

➰ cURL:

curl --location 'localhost:8000/v2/share/document?document=&notify=true' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "visits": 1,
  "share_to": [
    ""
  ]
}'

The code for the following endpoint can be reviewed from app/api/routes/document_sharing.py under share_document.

It takes the following argument:

document (Union[str, UUID]): The ID or UUID of the document to be shared.
share_request (SharingRequest): The sharing request containing the recipients and permissions.
notify (bool, optional): Whether to send notifications to the recipients. Defaults to True.
repository (DocumentSharingRepository, optional): The repository for document sharing operations.
document_repo (DocumentRepository, optional): The repository for document operations.
metadata_repo (DocumentMetadataRepository, optional): The repository for document metadata operations.
notify_repo (NotifyRepo, optional): The repository for notification operations.
auth_repo (AuthRepository, optional): The repository for authentication operations.
user (TokenData, optional): The authenticated user.

Here, we send a file to users via mail as an attachment, and here it's not mandatory for user to whome we are sharing a file to have a account on docflow.

How sharing as attachment works is, we use tempfile, a python library for creating a temporary file. Here is a code snippet of how its done.

# Creating temp file to share
with tempfile.NamedTemporaryFile(delete=True, suffix=extension) as temp:
    temp.write(file)
    temp_path = temp.name

    subject = f"{owner.username} shared a file with you using DocFlow"
    for mails in share_to:
        content = f"""
        Hello {mails}! 
        
        Hope you are well? {owner.username} | {user_mail} shared a file with you as an attachment. 
        
        Regards,
        DocFlow
        """
        mail_service(mail_to=mails, subject=subject, content=content, file_path=temp_path)

So for all the mail ids the user enters in share_to, mail_service() is called.

And this is how mailing in DocFlow works...