How to Dynamically Convert File Paths on Azure Storage Using Cantaloupe Delegate Scripts

Introduction

When using Azure Storage with the IIIF server Cantaloupe, there are cases where the IIIF URL identifier differs from the actual file path on Azure Storage. This article explains in detail how to solve this problem using delegate scripts.

Problem

Suppose you are managing images with the following file structure:

However, you want to access them via IIIF URLs like the following:

In this case, the IIIF URL identifier (collection1/item001/item001_001.jpg) differs from the actual Azure Storage path (images/collection1/item001/item001_001.jpg).

Since AzureStorageSource does not have a PATH_PREFIX setting like S3Source, delegate scripts must be used to solve this problem.

Solution

1. Docker Compose Configuration

2. Delegate Script (delegates.rb)

Development/Debug Version

First, verify the behavior with a version that includes debug output:

Clean Production Version

After verifying the behavior, remove debug output for production:

Troubleshooting

Common Errors and Solutions

1. Cannot invoke "edu.illinois.library.cantaloupe.delegate.DelegateProxy.getAzureStorageSourceBlobKey()" because the return value is null

Cause: Delegate script is not loaded correctly or has a syntax error

Solution:

• Check the delegate script syntax: ruby -c delegates.rb
• Verify that attr_accessor :context is defined
• Check the container logs for delegate script loading status

2. undefined method 'context=' for CustomDelegate

Cause: attr_accessor :context is not defined

Solution: Add attr_accessor :context at the beginning of the class

3. undefined method 'pre_authorize' etc.

Cause: Required delegate methods are not defined

Solution: Add the necessary methods, referring to the complete delegate script above

4. class org.jruby.RubyHash cannot be cast to class java.lang.String

Cause: metadata() method is returning an incorrect type

Solution:

• Return nil when metadata is not used
• It is important to return nil rather than an empty hash {}

Debugging Methods

1. Log monitoring:

2. Syntax check:

3. Incremental testing: Start with a simple delegate script and gradually add features

Verification

1. Start the Service

2. Test Access

3. Check Logs (When Using Debug Version)

Expected log output:

0

Summary

By using Cantaloupe’s delegate script, you can absorb the difference between IIIF URLs and actual storage paths. Key points:

1. ScriptLookupStrategy setting: Required for using delegate scripts with AzureStorageSource
2. attr_accessor :context: Required for Cantaloupe to set context information
3. azurestoragesource_blob_key method: Main logic for path conversion
4. Other delegate methods: Minimally required to avoid errors

The method introduced in this article enables flexible file management and IIIF URL design. It is particularly effective when you want to add IIIF support without changing existing file structures.

Reference Links

• Cantaloupe User Manual - Delegate System
• Cantaloupe User Manual - Azure Storage Source
• IIIF Image API 3.0