Add URL-safe Base64 Encoding/Decoding for Dynamic Sample Redirection

[janvandenschilden]

What changes are being proposed?

This pull request introduces a new feature that allows JSON data to be encoded into a URL using base64 encoding. This enhancement enables dynamic redirection of users to specific samples without the need to create a separate JSON file for each possibility. The implementation includes a new utility class, UrlsafeCodec, which handles the encoding and decoding process, ensuring that the data is URL-safe.

Why are these changes necessary?

The changes address issue #133, which highlighted the need for a more efficient way to handle sample redirection. By encoding the JSON data directly into the URL, we can significantly simplify the process for users and maintainers alike, making the application more flexible and user-friendly.

How have these changes been tested?

The new encoding and decoding functionality has been thoroughly tested with various JSON data structures to ensure reliability and stability. Manual testing has been conducted to confirm that the feature works as expected in the application.

[sehilyi]

Thank you @janvandenschilden for making the first outside contribution to this repo!!

If I understand correctly, with this change, users can use the external parameter as is (i.e., specifying the URL of their data config file) but also include the JSON data directly in the URL after encoding the data using the UrlsafeCodec.encode function.

A few requests/questions:

• Are you aware of any standard library or even website (e.g., similar to https://www.urlencoder.org/) that encodes the JSON data in the same way? I am thinking about what would be the best option to help users prepare the JSON-encoded URL. Perhaps, the best way would be to support that directly on Chromoscope (or implement a dedicated webpage).
• Could you share a URL(s) that I can use to test the changes?

[janvandenschilden]

Hi @sehilyi

Thank you for the warm welcome and for considering my pull request. I’m happy to be the first external contributor to this project, and I’m equally excited that this is my first contribution to an external repository.

Regarding the implementation, the external parameter has been adapted with versatility in mind. It can be utilized in two ways:

By providing the URL to a data configuration file.
By supplying a base64 encoded string that represents the content of the JSON file.
For instance, given a JSON file named samples.json with specific content, users have the option to either link directly to the file via a URL like localhost:3000/app/?showSamples=true&external=http://path/to/samples.json, or they can encode the JSON content into a base64 string and include it directly in the URL: localhost:3000/app/?showSamples=true&external=base64-encoded-string.

To facilitate the encoding process, I’ve developed a utility component and a dedicated page within the application at the /dev/codec path. This feature allows users to easily convert their JSON data to a base64 encoded string and vice versa. I did explore existing libraries and online tools for this purpose, but found that they were not fully compatible. Hence, the decision to create an in-app solution. However, please use it (or not use it) as you see fit, it is mainly here for demonstration purposes.

As an example, I will give an example of json file and what it is encoded to.

[
{
        "group": "default",
        "id": "9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa",
        "cancer": "kidney",
        "assembly": "hg19",
        "sv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.pcawg_consensus_1.6.161022.somatic.sv.bedpe",
        "cnv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.consensus.20170119.somatic.cna.annotated.txt",
        "vcf": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz",
        "vcfIndex":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz.tbi",
        "vcf2": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.consensus.20161006.somatic.indel.sorted.vcf.gz",
        "vcf2Index":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/9ae0744a-9bc1-4cd7-b7cf-c6569ed9e4aa.consensus.20161006.somatic.indel.sorted.vcf.gz.tbi",
        "thumbnail": "_9ae0744a"
},
{
        "group": "default",
        "id": "b27d75ba-5989-4200-bfe9-f1b7d7cf8008",
        "cancer": "breast",
        "assembly": "hg19",
        "sv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.pcawg_consensus_1.6.161022.somatic.sv.bedpe",
        "cnv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.consensus.20170119.somatic.cna.annotated.txt",
        "vcf": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz",
        "vcfIndex":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz.tbi",
        "vcf2": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.consensus.20161006.somatic.indel.sorted.vcf.gz",
        "vcf2Index":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/b27d75ba-5989-4200-bfe9-f1b7d7cf8008.consensus.20161006.somatic.indel.sorted.vcf.gz.tbi",
        "thumbnail": "_b27d75ba"
},
{   
        "group": "default",
        "id": "fc8edf46-2005-1af4-e040-11ac0d481414",
        "cancer": "breast",
        "assembly": "hg19",
        "sv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/fc8edf46-2005-1af4-e040-11ac0d481414.pcawg_consensus_1.6.161022.somatic.sv.bedpe",
        "cnv": "https://s3.amazonaws.com/gosling-lang.org/data/SV/fc8edf46-2005-1af4-e040-11ac0d481414.consensus.20170119.somatic.cna.annotated.txt",
        "vcf": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/fc8edf46-2005-1af4-e040-11ac0d481414.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz",
        "vcfIndex":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/fc8edf46-2005-1af4-e040-11ac0d481414.consensus.20160830.somatic.snv_mnv.sorted.vcf.gz.tbi",
        "vcf2": "https://somatic-browser-test.s3.amazonaws.com/browserExamples/fc8edf46-2005-1af4-e040-11ac0d481414.consensus.20161006.somatic.indel.sorted.vcf.gz",
        "vcf2Index":"https://somatic-browser-test.s3.amazonaws.com/browserExamples/fc8edf46-2005-1af4-e040-11ac0d481414.consensus.20161006.somatic.indel.sorted.vcf.gz.tbi",
        "thumbnail": "_fc8edf46"
}
]

zdRNb5swGMDx78K5NjZ1APe.w86Tdpmm6LH9QFHBRtghaad.9zlKk1VattEokN38Jvmn5_D_9iOpB7fpk4fEYAWbNiR3SWPiVgKyQgggUmlOhDYFUYWuiM5XuUQjUQDEtxqsxiG.f2qMxed4At5jp9rnePZYcxlP_Lhfh9D7hzT19xQ6eHEWtp5q16W1821ja9KCrakb6tRAgPTL13SKgPYatvVaO.vR.o1fc5pTnnOWZdS7DkKjqR.pQtPjXmtnpJwQNGO8YJzLE0FboGCtCxDQ0LDbT3nU1XvL4SVRg9t6HEhAH.hvwLfbTzvo.hb9Ba6clffs12jsuO7sGPfDHhZJtH452D5bg7v_E0iDag7I7BZAzlh.AjZxTO25.WU3G.C_fG_jC4.bTllo2mhcH79JXu_.WASVFaZYKSArWUoiMsaIqlCSiqt4oauSsfJ9EdSA4MM1izBFsFARJlFuUISPuxYuwizAaxbhAuCiRZjBd64Ix2_.VoRKl2gqkZOIWBEOlSDIBCOcg2ZGlFxwMW8RpggWKsIkyg2K8HHXwkWYBXjNIlwAXLQIM_jOFeH4TfL6_Sc-

[sehilyi]

I realized this change makes the demo of the chromoscope inaccessible via chromoscope.bio/app. I tested this by running the following commands.

# build both the documentation and demo and create a "\build" folder to organize files
yarn predeploy

# enables browsing the built project (i.e., doc and demo) by running a local server
http-server ./build

How the document and demo are organized under \build:

build
   - index.html // ← documentation (i.e., "chromoscope.bio")
   - ...
   - app
      - index.html // ← demo (i.e., "chromoscope.bio/app")
      - ...

By setting base: '/app/', the index.html file for the demo (i.e., app/index.html) created by vite has proper relative paths (e.g., app/index.js instead of index.js). So, without setting the base option, chromoscope.bio/app (app/index.html) ends up having the wrong relative paths, making the demo not work.

I did not find a simple way to walk around this and would need to experiment more for a better alternative, but we can simply create an inlined HTML file for the webpage that you created (instead of using React) and put that under a /dev/codec/ folder.

build
   - index.html // ← documentation (i.e., "chromoscope.bio")
   - ...
   - app
      - index.html // ← demo (i.e., "chromoscope.bio/app")
      - ...
   - dev
      - codec
         - index.html // ← simple page to convert JSON to str

In this way, users should be able to access the webpage via "chromoscope.bio/dev/codec/'.