Resources

Nitric provides cloud-native building blocks that make it simple to declare the resources you need as part of your application code.

The Nitric deployment engine will run through your code at deployment time, collecting a graph of all the required resources and their interactions. This information is forwarded to a Nitric plugin during deployment, which provisions the resources in the cloud.

During development though, you can interact with these resources as if they were local objects, making it easy to build and test your application. Here we'll discuss the different types of resources you can declare in Nitric, and some best practices for working with them.

Types of Resources

Nitric supports many recognizable cloud resources, such as:

• HTTP APIs: Expose an HTTP API to the internet.
• Websocket APIs: Expose a websocket API to the internet.
• Schedule: Run a function callback on a schedule.
• Batch Jobs: Run high-performance computing tasks, data processing, or tasks requiring GPUs, or a large number of vCPUs or memory.
• Topic: Publish and subscribe to messages between services.
• Queue: Send and receive messages between services.
• Bucket: Store and retrieve files in the cloud, and implement callbacks that run on file change events.
• SQL Databases: Deploy and interact with SQL databases, like PostgreSQL.
• Key/Value Stores: Store and retrieve data key/value data.
• Secrets: Store and retrieve sensitive data securely, such as API keys, passwords or database credentials.

Rules

In order for Nitric to enable resource declarations with existing language features, there are a few rules to keep in mind when declaring Nitric resources as part of your application. Most of these rules are easy to follow and are good practice for writing clean, maintainable code.

Don't declare resources in runtime code, like callbacks

Nitric needs to be aware of resources at deployment time so they can be deployed appropriately. Declaring resources at runtime means the resource won't be declared when deploying your application. Consequently, the resource will not be provisioned to the cloud.

The Nitric deployment engine does not evaluate runtime code at deployment time as this could result in unintended behavior or side effects.

A working example:

import { api, bucket } from '@nitric/sdk'

// ✅ This declaration will work
const files = bucket('files').allow('read')

api('public').get('/files/:name', (ctx) => {
  // ❌ This declaration won't work, since it's in a callback that's only called at runtime.
  const badBucket = bucket('wont-work').allow('read')
})

Don't use runtime methods in top level code

Calling runtime methods in top-level code can lead to unintended side effects. Nitric resources should be accessed in a deterministic way to avoid unintentional side-effects.

A working example:

import { api, bucket } from '@nitric/sdk'

const files = bucket('files').allow('read')

// ❌ This access will not work.
const fileContents = files.file('example.txt').read()

api('public').get('/files/:name', (ctx) => {
  // ✅ This access will work.
  const fileContents = files.file('example.txt').read()
})

import { api, bucket } from '@nitric/sdk'

const files = bucket('files').allow('read')

// 👀 Singleton value
let fileContents: string

// Lazy access method
const getFileContents = async () => {
  if (!fileContents) {
    fileContents = await files.file('example.txt').read()
  }

  return fileContents
}

api('public').get('/files/:name', (ctx) => {
  const fileContents = await getFileContents()
})

Best Practices

✅ Re-use declarations for shared resources

When many services share a resource it's helpful to re-use resource declaration like any other variable in your code.

For example:

❌ Avoid declaring permissions for shared resources

Creating resource permissions in the same context as the resources can make those permissions leak. This is demonstrated in the below example:

In this scenario, both service-one and service-two have read access to both buckets, even though each service is only using one of the buckets. This is because they are declared in the same context and evaluated at the same time in each of the services.

Resource permissions should always be declared in the scope of a single service unless the permissions required by one or more services are identical.