Skip to content

File Services

Jump to bottom
Ryder Johnson edited this page Oct 25, 2025 · 2 revisions

Welcome to Juno's File Service! This guide will walk you through the steps required to integrate Juno’s file microservice into your project.

By following this documentation, your team will be able to set up, configure, and manage files directly through Juno’s SDK.

This guide will focus solely on the File Service SDK interactions. When a new release of Juno is deployed, all documentation will be automatically regenerated to ensure it stays up to date.

Prerequisites

  1. Access to Juno: Ensure you have access to the Juno SDK. You’ll need an API key specific to your project to interact with the file service.
  2. Project Registration: Your project should already be registered in Juno. If not, please take a look at the Infra Project Registration Guide.
  3. API Key: You will need an API key generated for your project. This key allows you to authenticate API requests.
  4. Install and Import Juno SDK:
npm install juno-sdk # for projects using npm
pnpm add juno-sdk # for projects using pnpm
yarn add juno-sdk # for projects using yarn
bun install juno-sdk # for projects using bun
import juno from "juno-sdk";

// Call this somewhere in your program before using any of Juno's services
juno.init({
  apiKey: "<your api key>",
  baseUrl: "<base url of Juno's API Gateway instance>"
});

// We can then call any of the service methods, e.g. email, file services

Data Models

Please take a moment to review the model structure of the File Service. The File Service organizes files using the following hierarchy:

  • File Config: consists of project ID and config environment. Each file config defines an environment (development, staging, production, test, etc) your project’s file service is currently maintaining
  • File Provider: consists of provider name, access keys, provider base URL, and metadata, indicating which cloud provider (S3, Azure, etc) is used to manage the files
  • File Bucket: consists of bucket name. Think of it as a folder containing the files
  • File: consists of file ID and metadata, representing a file that can be uploaded/downloaded

image

Step 1: Configure Juno File Services

Begin by setting up the file service configuration for your project. This involves creating a file config object that includes your project ID and target environment, which will then be saved to the Juno Database.

This configuration process automatically extracts your project ID and environment from your API key. You do not have to specify these info as arguments to the method

These file config objects define the environments that your project's file service is maintaining. Any buckets or files created in the future will be linked to one of these configs, ensuring that files are correctly managed and accessed within the appropriate environment.

// Your API key already contains your project ID and target environment
// The method will auto-extract these info to set up your file service

juno.file.setup();

// If successful, you will receive { success: true }

View created configuration:

You can retrieve created file configuration as follows:

// This method will extract the specified environment in your API Key
// The returned file config will be the config associated with the environment

const projectId: string = "0";
juno.settings.getFileConfig(projectId);

If successful, you should get a file config with the following structure:

{
  // File Configuration ID
  'id': number;
  
  // The configured environment
  'environment': string;

   // The list of files associated with the config
  'files': Array<File>;
  
   // The list of buckets associated with the config
  'buckets': Array<FileBucket>;
}

Example value:

{
  "id": 0,
  "environment": "production",
  "files": [
    {
      "fileId": {
	      "bucketName": "bucket-sample";
		    "configId": 0;
		    "configEnv": "production";
		    "path": "file-sample";
      },
      "metadata": "<file metadata here>"
    }
  ],
  "buckets": [
    {
      "name": "bucket-sample",
      "configId": 0,
      "configEnv": "production",
      "fileProviderName": "infra-s3",
      "FileServiceFile": [
        {
		      "bucketName": "bucket-sample";
			    "configId": 0;
			    "configEnv": "production";
			    "path": "file-sample";
	      }
      ]
    }
  ]
}

Step 2: Register File Provider

You will then register your file provider of choice with Juno. This involves saving to the Juno Database the file provider information such as:

  • providerName
  • baseURL
  • type You will choose one of the provider types supported by Juno

You will also provide your accessKey , which includes:

  • publicAccessKey This should be accessKeyId (in S3) or accountName (in Azure)
  • privateAccessKey This should be secretAccessKey (in S3) or accountKey (in Azure)

Registering your file provider along with your access keys allows Juno to manage your files and buckets through your file provider account.

const provider = {
	"providerName": "infra-s3",
	"baseUrl": "http://s3.amazonaws.com",
	"type": FileProviderType.S3, // Choose provider from the FileProviderType enum
	"accessKey": {
		"publicAccessKey": "my-publicAccessKey", // Don't store these in plaintext
		"privateAccessKey": "my-privateAccessKey", // Don't store these in plaintext
	},
};
juno.file.registerFileProvider(provider);

If successful, the method will return an object with the following structure:

{
  // The unique provider name of the file provider
  'providerName': string;
  
  // The metadata of the file provider
  'metadata': string;
}

Example value:

{
  'providerName': "infra-s3",
  'metadata': "<provider metadata here>";
}

Step 3: Register File Bucket

Next, you will create file buckets to organize your files. Here, you will provide:

  • name Name of bucket
  • configId File config ID you would like to associate with your bucket
  • fileProviderName File provider to register your bucket
  • fileIds file IDs to be linked to this bucket

Juno also extracts the environment specified in your API Key as part of the inputs to this method

Make sure your file config and provider exists in Juno before calling this method

Juno will call the specified file provider API to create a bucket in the cloud and save the bucket information to Juno Database. You should be able to see the bucket in your provider portal

Note: Juno will use your provider credentials to access and manage your files/buckets

const bucket = {
	"name": "bucket-sample",
	"configId": 0,
	"fileProviderName": "infra-s3",
	"fileIds": [],
};
juno.file.registerFileBucket(bucket);

If successful, the method will return an object with the following structure:

{
  // The unique name of the registered bucket
  'name': string;
  
  // Configuration ID associated with the registered bucket
  'configId': number;

   // The config environment associated with the bucket
  'configEnv': string;

   // The name of the file provider associated with the bucket
  'fileProviderName': string;

   // The list of file identifiers associated with the bucket
  'fileServiceFile': Array<object>;
}

Example value:

{
  'name': "bucket-sample",
  'configId': 0,
  'configEnv': "production",
  'fileProviderName': "infra-s3",
  'fileServiceFile': [],
}

Step 4: Upload File

At this stage, you should have all the setups you need to begin managing your files!

To upload a file:

  1. Register your file with Juno → Juno will record the file information to Juno Database and contact the file provider in the request to generate a presigned URL
  2. Use this presigned URL to upload the file directly to the file provider platform. For more information, please refer to S3 Presigned URL or Azure SAS

The upload method requires the following inputs:

  • fileName Name of the file to be uploaded
  • bucketName Name of bucket that will contain the file
  • providerName Name of file provider that handle the file upload
  • configId File config ID you would like to associate with your file
  • region optional - region used by file provider to upload the file

Juno also extracts the environment specified in your API Key as part of the inputs to this method

Make sure your file config, provider, and bucket exists in Juno before calling this method

Note: Juno will use your provider credentials to access and manage your files/buckets

const file = {
	"fileName": "file-sample",
	"bucketName": "bucket-sample",
	"providerName": "infra-s3",
	"configId": 0,
	"region": "us-east-1",
};
juno.file.uploadFile(file);

If successful, the method will return an object with the following structure:

{
	// Pre-signed URL used in file upload
  'url': string;
}

Step 5: Download File

Once you uploaded files, you can now download a file!

To download a file:

  1. Request a presigned URL from Juno → Juno will check if the file is registered with Juno Database and contact the file provider in the request to generate a presigned URL
  2. Use this presigned URL to download the file directly from the file provider platform. For more information, please refer to S3 Presigned URL or Azure SAS

The download method requires the following inputs:

  • fileName Name of the file to be downloaded
  • bucketName Name of bucket that contains the file
  • providerName Name of file provider that handle the file download
  • configId File config ID associated with the file
  • region optional - region used by file provider to download the file

Juno also extracts the environment specified in your API Key as part of the inputs to this method

Make sure your file config, provider, and bucket exists in Juno before calling this method

Note: Juno will use your provider credentials to access and manage your files/buckets

const file = {
	"fileName": "file-sample",
	"bucketName": "bucket-sample",
	"providerName": "infra-s3",
	"configId": 0,
	"region": "us-east-1",
};
juno.file.downloadFile(file);

If successful, the method will return an object with the following structure:

{
	// Pre-signed URL used in file download
  'url': string;
}

Step 6: Error Handling

@ApiUnauthorizedResponse

→ Make sure your API key has the permission to perform the action

@ApiBadRequestResponse

→ Make sure your input arguments have correct typings and contain all required fields.

→ Make sure any provided ID or name exists in Juno when retrieving data or associating an object with other objects

→ Make sure not to create objects with duplicate IDs or name

@ApiNotFoundResponse

→ Make sure any provided ID or name exists in Juno when retrieving data or associating an object with other objects

@ApiInternalServerErrorResponse

→ A problem occurred on Juno’s side. If this happens, please contact support.

For a full list of possible error codes and detailed descriptions, please refer to the Juno Documentation or contact the infra team for more information.

Infra Support

If you encounter any issues or need help, you can reach out through the following channels:

  • Slack: Join the #gt-infra-support channel for real-time assistance.

Conclusion

You are now ready to integrate Juno’s file service into your project! For more advanced configurations or questions, refer to the Juno Documentation or reach out to the infra team for support.

Clone this wiki locally