m365_active_storage 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248f6e95435a9737f6aa06db40f6d758a59a4d6355ad4399a12d5dbc0d24efde
-  data.tar.gz: c93ea5f7c16c419e2cfadbc9ce6a679b1a0abb533bb9863b9a75f8b7aed7d17d
+  metadata.gz: 1d083b38ef3eacb7fa4d749c7c8a1de3c11fd3e8e86350d11c9533f9f295034e
+  data.tar.gz: b8db90e6bd4d2f16c5664ae495cdf4efed60af27fe42bb6823dc4d68bd729e73
 SHA512:
-  metadata.gz: 91d7ddd980e2959d4c834847affd9b515f1544c307fa00d562bf6c15b3754fa3c1d657ed648c03eb285eb7cd3a98daf75dc23c5c888bc88d1914fc19cd249528
-  data.tar.gz: d8cedd464a2fb9946f778b79b3113e1176aa4d444d56b271bfda1378a386a3765c21850279325a78b3af1a3c5547b5f85a3fe42857652e9b002e3d814cace891
+  metadata.gz: d307d02eb5b143fd26c31cb9711d71e4d8f4668589c830334bc90158615b41138b151f1c125ce2ee8b0c5f05198c24befdcb0478cb176fd74f2935ae407cc010
+  data.tar.gz: 771e399e44037c9a5637d82b16f9cb0ba3d23d42ea699dfcfc70deef533e9873aeec3f3a2cf64df9727917e9164b99615e0da99c8ca8840548f0b49645484055

data/README.md

@@ -27,6 +27,7 @@ sharepoint:
   oauth_secret:
   sharepoint_site_id:
   sharepoint_drive_id:
+  storage_key:
 ```
 #### -- or --
 
@@ -40,8 +41,42 @@ OAUTH_APP_ID=
 OAUTH_SECRET=
 SHAREPOINT_SITE_ID=
 SHAREPOINT_DRIVE_ID=
+STORAGE_KEY=
 ```
 
+### Set storage key
+The storage key set when the file is stored using the blob key or the filename.
+```ruby
+storage_key: key | filename
+```
+#### Using the key store:
+Stores the files with the blob key in the sharepoint drive, with no extension. If 
+a file is uploaded more than once will be stored each time.
+
+#### Using the filename store:
+Stores the files using the filename instead of the key. In this case
+a if a file is uploaded twice only the last will remain in the sharepoint drive.
+
+With the filename storage, it's possible to manage folders to store the documents, allowing having
+files with the same name into different folders.
+
+In your app the path of the file can be set on the document attach:
+```ruby
+model.attachment.attach(
+  io: file,
+  filename: file.original_filename,
+  metadata: { "sharepoint_folder" => "documents/#{Date.today.year}/#{Date.today.strftime('%m')}" }
+)
+```
+This will create or use the nested folder structure, in this example:
+```shell
+documents/
+  2026/
+    03/
+```
+
+
+
 ### Set active storage to sharepoint service
 In the app config/environments/`<environment>`.rb
 

data/config/storage.yml

@@ -7,4 +7,5 @@ sharepoint:
   app_id: <%= Rails.application.credentials.dig(:sharepoint, :oauth_app_id) || ENV["OAUTH_APP_ID"] %>
   secret: <%= Rails.application.credentials.dig(:sharepoint, :oauth_secret) || ENV["OAUTH_SECRET"] %>
   site_id: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_site_id) || ENV["SHAREPOINT_SITE_ID"] %>
-  drive_id: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_drive_id) || ENV["SHAREPOINT_DRIVE_ID"] %>
+  drive_id: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_drive_id) || ENV["SHAREPOINT_DRIVE_ID"] %>
+  storage_key: <%= Rails.application.credentials.dig(:sharepoint, :sharepoint_storage_key) || ENV["SHAREPOINT_STORAGE_KEY"] %>

data/lib/active_storage/configuration.rb

@@ -70,7 +70,7 @@ module M365ActiveStorage
   class Configuration
     attr_reader :ms_graph_url, :ms_graph_version, :ms_graph_endpoint,
                 :auth_host, :tenant_id,
-                :app_id, :secret, :site_id, :drive_id
+                :app_id, :secret, :site_id, :drive_id, :storage_key
 
     # Initialize Configuration with the provided parameters
     #
@@ -86,6 +86,7 @@ module M365ActiveStorage
     # @option options [String] :secret The Azure AD client secret
     # @option options [String] :site_id The SharePoint site ID
     # @option options [String] :drive_id The SharePoint drive ID
+    # @option options [String] :storage_key The SharePoint storage key
     #
     # @raise [KeyError] if any required parameter is missing or empty
     #
@@ -98,7 +99,7 @@ module M365ActiveStorage
     #
     # @see #validate_configuration!
     def initialize(**options)
-      fetch_configuration_params(options)
+      fetch_configuration_params(options.with_indifferent_access)
       validate_configuration!
     rescue KeyError => e
       raise KeyError, "Configuration error: #{e.message}"
@@ -114,7 +115,6 @@ module M365ActiveStorage
     # @return [void]
     # @raise [KeyError] if any required parameter is missing
     def fetch_configuration_params(options)
-      options = options.with_indifferent_access
       @auth_host = options.fetch(:auth_host)
       @tenant_id = options.fetch(:tenant_id)
       @app_id = options.fetch(:app_id)
@@ -124,6 +124,7 @@ module M365ActiveStorage
       @site_id = options.fetch(:site_id)
       @drive_id = options.fetch(:drive_id)
       @ms_graph_endpoint = "#{@ms_graph_url}/#{@ms_graph_version}"
+      @storage_key = options.fetch(:storage_key) || "key"
     end
 
     # Validate that all required configuration parameters are present and non-empty

data/lib/active_storage/service/sharepoint_service.rb

@@ -142,12 +142,15 @@ module ActiveStorage
     #
     # @see #get_storage_name
     # @see #handle_upload_response
+    # @see #ensure_folder_path
     def upload(key, io, **)
       auth.ensure_valid_token
-      storage_name = get_storage_name(key)
-      upload_url = "#{drive_url}/root:/#{CGI.escape(storage_name)}:/content"
+      folder_path = sharepoint_folder_for(key)
+      ensure_folder_path(folder_path)
+      storage_path = build_storage_path(get_storage_name(key), folder_path)
+      upload_url = "#{drive_url}/root:/#{encode_storage_path(storage_path)}:/content"
       response = http.put(upload_url, io.read, { "Content-Type": "application/octet-stream" })
-      handle_upload_response(response)
+      handle_upload_response(key, response)
     end
 
     # Download a file from SharePoint
@@ -185,9 +188,11 @@ module ActiveStorage
     # @see #download
     def fetch_download(key)
       auth.ensure_valid_token
-      storage_name = get_storage_name(key)
-      download_url = "#{drive_url}/root:/#{CGI.escape(storage_name)}:/content"
-      http.get(download_url)
+      download_url = sharepoint_content_url_for(key)
+      response = http.get(download_url)
+      return response unless should_retry_with_path_url?(key, response)
+
+      http.get(legacy_content_url_for(key))
     end
 
     # Handle the HTTP response from a download request
@@ -249,20 +254,25 @@ module ActiveStorage
     #
     # @see #download_chunk
     def fetch_chunk(key, range)
-      storage_name = get_storage_name(key)
-      download_url = "#{drive_url}/root:/#{CGI.escape(storage_name)}:/content"
-      http.get(download_url, { "Range": "bytes=#{range.begin}-#{range.end}" })
+      download_url = sharepoint_content_url_for(key)
+      response = http.get(download_url, { "Range": "bytes=#{range.begin}-#{range.end}" })
+      return response unless should_retry_with_path_url?(key, response)
+
+      http.get(legacy_content_url_for(key), { "Range": "bytes=#{range.begin}-#{range.end}" })
     end
 
     # Delete a file from SharePoint
     #
-    # Removes a file from the SharePoint drive. Requires the filename to be available
-    # from the PendingDelete registry (set before the blob was deleted).
+    # Removes a file from the SharePoint drive.
+    #
+    # It prefers deletion by SharePoint item ID and falls back to filename when
+    # the item ID is not available. When the blob record has already been deleted,
+    # it reads pending data from PendingDelete.
     #
     # @param [String] key The blob key to delete
     # @return [Boolean] true if deletion was successful (204 response)
     #
-    # @raise [StandardError] if filename not found or deletion fails
+    # @raise [StandardError] if identifier not found or deletion fails
     #
     # @example
     #   success = service.delete("key123")  # => true
@@ -271,12 +281,10 @@ module ActiveStorage
     # @see M365ActiveStorage::Railtie
     def delete(key)
       auth.ensure_valid_token
-      # get the filename from the pending deletes storage
-      # because once the blob is deleted, we can no longer get the filename from the blob record
-      storage_name = M365ActiveStorage::PendingDelete.get(key)
-      raise "Filename not found for key #{key}. Cannot delete file from SharePoint." unless storage_name
 
-      delete_url = "#{drive_url}/root:/#{CGI.escape(storage_name)}"
+      delete_url = sharepoint_delete_url_for(key)
+      raise "Identifier not found for key #{key}. Cannot delete file from SharePoint." unless delete_url
+
       response = http.delete(delete_url)
       response.code.to_i == 204
     end
@@ -301,8 +309,7 @@ module ActiveStorage
     #   service.exist?("key123")  # => true or false
     def exist?(key)
       auth.ensure_valid_token
-      storage_name = get_storage_name(key)
-      check_url = "#{drive_url}/root:/#{CGI.escape(storage_name)}"
+      check_url = sharepoint_item_url_for(key)
       response = http.get(check_url)
       response.code.to_i == 200
     end
@@ -353,16 +360,231 @@ module ActiveStorage
     # Validates that the upload succeeded (201 Created or 200 OK).
     # Raises an error for any other status code.
     #
+    # @param [String] key The Active Storage blob key associated with the upload
     # @param [Net::HTTPResponse] response The HTTP response from the upload
     # @return [void]
     #
     # @raise [StandardError] if upload failed
-    def handle_upload_response(response)
-      return if [201, 200].include?(response.code.to_i)
+    def handle_upload_response(key, response)
+      if [201, 200].include?(response.code.to_i)
+        persist_sharepoint_id(key, response)
+        return
+      end
 
       raise "Failed to upload file to SharePoint"
     end
 
+    # Persist the SharePoint item id in blob metadata after successful upload.
+    #
+    # Stored keys:
+    # * metadata["sharepoint_id"] - convenience flat key for quick access
+    # * metadata["sharepoint"]["id"] - namespaced SharePoint metadata
+    #
+    # @param [String] key The Active Storage blob key
+    # @param [Net::HTTPResponse] response The successful upload response body
+    # @return [void]
+    def persist_sharepoint_id(key, response)
+      return if response.body.to_s.strip.empty?
+
+      payload = JSON.parse(response.body)
+      sharepoint_id = payload["id"]
+      return if sharepoint_id.to_s.empty?
+
+      blob = ActiveStorage::Blob.find_by(key: key)
+      return unless blob
+
+      metadata = blob.metadata.is_a?(Hash) ? blob.metadata.dup : {}
+      sharepoint_metadata = metadata["sharepoint"].is_a?(Hash) ? metadata["sharepoint"].dup : {}
+
+      sharepoint_metadata["id"] = sharepoint_id
+      metadata["sharepoint"] = sharepoint_metadata
+      metadata["sharepoint_id"] = sharepoint_id
+
+      blob.update_columns(metadata: metadata)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Resolve the SharePoint content URL for a blob key.
+    #
+    # Preference order:
+    # 1) Blob metadata sharepoint_id (stable item reference)
+    # 2) Filename/key path fallback for backwards compatibility
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String] The content URL to download from SharePoint
+    def sharepoint_content_url_for(key)
+      sharepoint_id = sharepoint_item_id_for(key)
+      return "#{drive_url}/items/#{CGI.escape(sharepoint_id)}/content" if sharepoint_id.present?
+
+      legacy_content_url_for(key)
+    end
+
+    # Build the legacy path-based content URL for a blob key.
+    #
+    # Includes folder path when present in blob metadata.
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String] Path-based content URL
+    def legacy_content_url_for(key)
+      "#{drive_url}/root:/#{encode_storage_path(get_storage_path(key))}:/content"
+    end
+
+    # Retry with path URL only when ID-based lookup was attempted and failed.
+    #
+    # @param [String] key The Active Storage blob key
+    # @param [Net::HTTPResponse] response The response from the ID-based request
+    # @return [Boolean] true when a path fallback should be attempted
+    def should_retry_with_path_url?(key, response)
+      sharepoint_item_id_for(key).present? && [400, 404].include?(response.code.to_i)
+    end
+
+    # Resolve the SharePoint item URL for a blob key.
+    #
+    # Preference order:
+    # 1) Blob metadata sharepoint_id
+    # 2) Filename/key path fallback
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String] SharePoint item URL (without /content)
+    def sharepoint_item_url_for(key)
+      sharepoint_id = sharepoint_item_id_for(key)
+      return "#{drive_url}/items/#{CGI.escape(sharepoint_id)}" if sharepoint_id.present?
+
+      "#{drive_url}/root:/#{encode_storage_path(get_storage_path(key))}"
+    end
+
+    # Resolve the SharePoint delete URL for a blob key.
+    #
+    # Since blob records may already be deleted when Active Storage calls #delete,
+    # this method also checks PendingDelete data captured in before_destroy.
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String, nil] URL to delete, or nil when no identifier could be resolved
+    def sharepoint_delete_url_for(key)
+      sharepoint_id = sharepoint_item_id_for(key)
+      return "#{drive_url}/items/#{CGI.escape(sharepoint_id)}" if sharepoint_id.present?
+
+      pending_delete = M365ActiveStorage::PendingDelete.get(key)
+      if pending_delete.is_a?(Hash)
+        pending_sharepoint_id = pending_delete["sharepoint_id"] || pending_delete[:sharepoint_id]
+        return "#{drive_url}/items/#{CGI.escape(pending_sharepoint_id)}" if pending_sharepoint_id.present?
+
+        storage_name  = pending_delete["filename"] || pending_delete[:filename]
+        folder_path   = pending_delete["sharepoint_folder"] || pending_delete[:sharepoint_folder]
+        storage_path  = build_storage_path(storage_name, folder_path)
+      else
+        storage_path = pending_delete
+      end
+
+      storage_path = key if storage_path.blank? && @config.storage_key.downcase == "key"
+      return nil if storage_path.blank?
+
+      "#{drive_url}/root:/#{encode_storage_path(storage_path)}"
+    end
+
+    # Read the SharePoint folder path from blob metadata.
+    #
+    # The app sets this before attaching a file:
+    #
+    #   blob.metadata["sharepoint_folder"] = "documents/invoices"
+    #   record.file.attach(io: file, filename: "doc.pdf",
+    #                      metadata: { "sharepoint_folder" => "documents/invoices" })
+    #
+    # Supports nested paths: "level1/level2/level3"
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String, nil] Folder path or nil when not set
+    def sharepoint_folder_for(key)
+      blob = ActiveStorage::Blob.find_by(key: key)
+      return nil unless blob&.metadata.is_a?(Hash)
+
+      blob.metadata["sharepoint_folder"].presence
+    end
+
+    # Build the full SharePoint storage path combining folder and filename.
+    #
+    # @param [String] filename The file name
+    # @param [String, nil] folder_path Optional folder path (e.g. "docs/invoices")
+    # @return [String] Combined path (e.g. "docs/invoices/document.pdf")
+    def build_storage_path(filename, folder_path = nil)
+      return filename if folder_path.blank?
+
+      "#{folder_path.to_s.chomp('/')}/#{filename}"
+    end
+
+    # Get the full storage path (folder + filename) for a blob key.
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String] Full storage path
+    def get_storage_path(key)
+      build_storage_path(get_storage_name(key), sharepoint_folder_for(key))
+    end
+
+    # Encode a storage path for use in a Microsoft Graph URL.
+    #
+    # Each path segment is CGI-encoded individually so that "/" separators
+    # are preserved and not encoded as "%2F".
+    #
+    # @param [String] path The path to encode (e.g. "my folder/sub folder/file.pdf")
+    # @return [String] URL-safe encoded path (e.g. "my+folder/sub+folder/file.pdf")
+    def encode_storage_path(path)
+      path.split("/").map { |s| CGI.escape(s) }.join("/")
+    end
+
+    # Ensure the full folder hierarchy exists in SharePoint.
+    #
+    # Walks through each segment of the path from root down, creating
+    # any folder that does not yet exist. Existing folders are silently skipped.
+    #
+    # @param [String, nil] folder_path The folder path to create (e.g. "docs/invoices/2024")
+    # @return [void]
+    def ensure_folder_path(folder_path)
+      return if folder_path.blank?
+
+      segments = folder_path.split("/").reject(&:blank?)
+      segments.each_with_index do |segment, index|
+        parent_path = segments[0...index].join("/")
+        create_sharepoint_folder(parent_path, segment)
+      end
+    end
+
+    # Create a single folder in SharePoint.
+    #
+    # Uses conflictBehavior "fail" and treats a 409 Conflict response as a
+    # no-op so the call is idempotent — safe to call even when the folder
+    # already exists.
+    #
+    # @param [String] parent_path Parent folder path relative to drive root
+    #   (empty string means drive root)
+    # @param [String] folder_name The name of the folder to create
+    # @return [void]
+    def create_sharepoint_folder(parent_path, folder_name)
+      url = if parent_path.present?
+              "#{drive_url}/root:/#{encode_storage_path(parent_path)}:/children"
+            else
+              "#{drive_url}/root/children"
+            end
+      body = { name: folder_name, folder: {}, "@microsoft.graph.conflictBehavior": "fail" }.to_json
+      http.post(url, body, { "Content-Type": "application/json" })
+      # 201 = created, 409 = already exists — both are acceptable outcomes
+    end
+
+    # Extract SharePoint item id from blob metadata.
+    #
+    # Supported metadata keys:
+    # * metadata["sharepoint_id"]
+    # * metadata["sharepoint"]["id"]
+    #
+    # @param [String] key The Active Storage blob key
+    # @return [String, nil] SharePoint item id if present
+    def sharepoint_item_id_for(key)
+      blob = ActiveStorage::Blob.find_by(key: key)
+      return nil unless blob&.metadata.is_a?(Hash)
+
+      blob.metadata["sharepoint_id"].presence || blob.metadata.dig("sharepoint", "id").presence
+    end
+
     # Get the storage name for a blob key
     #
     # Tries to use the blob's filename if available, otherwise falls back to the key.
@@ -376,6 +598,8 @@ module ActiveStorage
     #   # If blob exists: => "document.pdf"
     #   # If blob doesn't exist: => "abc123def456"
     def get_storage_name(key)
+      return key if @config.storage_key.downcase == "key"
+
       blob = ActiveStorage::Blob.find_by(key: key)
       return key unless blob.present? && blob.filename.present?
 

data/lib/m365_active_storage/railtie.rb

@@ -31,9 +31,9 @@ module M365ActiveStorage
   # === File Deletion Flow
   #
   # When a blob is destroyed and it's using the SharePoint service:
-  # 1. The before_destroy callback captures the blob's filename
+  # 1. The before_destroy callback captures blob metadata needed for deletion
   # 2. Stores it in PendingDelete for later retrieval
-  # 3. The filename can be used by the async deletion worker to clean up SharePoint
+  # 3. The async deletion worker can delete by SharePoint ID or filename fallback
   #
   # @see M365ActiveStorage::Files
   # @see M365ActiveStorage::PendingDelete
@@ -41,22 +41,30 @@ module M365ActiveStorage
   class Railtie < ::Rails::Railtie
     # Hook into Rails initialization to set up gem components
     config.after_initialize do
-      # Add before_destroy callback to ActiveStorage::Blob to capture filename
+      # Add before_destroy callback to ActiveStorage::Blob to capture deletion identifiers
       ::ActiveStorage::Blob.class_eval do
         before_destroy :store_filename_for_deletion, if: proc { |blob| blob.service.is_a?(::ActiveStorage::Service::SharepointService) }
 
         private
 
-        # Store the filename in the pending deletes storage before the blob is destroyed
+        # Store deletion identifiers in the pending deletes storage before the blob is destroyed
         #
         # This callback is triggered before a blob is destroyed from the database.
-        # It captures the blob's filename and stores it in PendingDelete so that
+        # It captures the blob's filename and SharePoint item ID (if present)
+        # and stores them in PendingDelete so that
         # asynchronous deletion processes can move the file to the recycle bin
         # in SharePoint.
         #
         # @return [void]
         def store_filename_for_deletion
-          M365ActiveStorage::PendingDelete.store(key, filename.to_s)
+          blob_metadata = metadata.is_a?(Hash) ? metadata : {}
+          sharepoint_id = blob_metadata["sharepoint_id"].presence || blob_metadata.dig("sharepoint", "id").presence
+          pending_delete_data = {
+            "filename"          => filename.to_s,
+            "sharepoint_id"     => sharepoint_id,
+            "sharepoint_folder" => blob_metadata["sharepoint_folder"].presence
+          }
+          M365ActiveStorage::PendingDelete.store(key, pending_delete_data)
         end
       end
     end

data/lib/m365_active_storage/version.rb

@@ -2,5 +2,5 @@
 
 module M365ActiveStorage
   # The version of the m365_active_storage gem
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: m365_active_storage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Óscar León