❗️

Notice

Resources are an experimental feature of Lever OS. Please report bugs as GitHub issues.

👍

Key takeaways

• Resources allow you to shard data across the instances of a service.
• Resource identifiers are just strings that Lever binds to specific instances.
• Traffic asking for a specific resource is consistently routed to the same instance.

Lever resources are identifiers that stick to the instance that first served them. This allows you to shard data across the instances of a service. Best illustrated with an example.

Suppose you have a service called myService and right now, it has 3 instances serving trafic. Invoking the service like so repeatedly

$ lever invoke /myService/someMethod

... will cause the requests to be sprinkled onto all 3 instances, with no guarantees of where it might land next.

But if we specify a resource as part of the invokation like so

$ lever invoke /myService/shinyResource/someMethod

... then we are guaranteed that each time the request will be handled by the same instance every time.

This allows you to cache relevant information about that resource in the instance's memory. The next time that resource is invoked you will be able to reuse the cached data.

The resource identifier can be any string. If Lever has never seen that identifier before it will bind it with an instance on the spot. Subsequent requests for that identifier will be routed to the same instance.

Although service and method names may not contain /, resource identifiers may. This allows you to create your own URL structure for resources belonging to the same service.

🚧

Important

Routing resources to the same instance is only guaranteed as long as that instance remains up. Lever OS may at any time stop that particular instance, which will cause that resource to be allocated to a different instance. Your implementation should handle this situation gracefully.

Handling resource invokations

Although each resource is handled by one instance at a time, each instance may handle more than one resource. It is the responsibility of the implementation of the methods to make the distinction when handling the request. The request identifier is typically passed as the first parameter (before the rest of the args) to the handling function - but you should consult the API reference for the language you are working with.

It is always a good idea to validate and sanitize resource identifiers. This is because for many public-facing services a rogue client can choose any resource string it wants, potentially causing injection attacks if not properly sanitized.

To help with managing resources on each instance, you can implement the methods below.

NewResource(resourceName) optional

• resourceName is the resource identifier.
• Returns null.

This Lever method is invoked by the Lever OS subsystem when a resource is linked to the instance handling this call. The NewResource invokation is guaranteed to be called before any invokation belonging to that resource is called.

CloseResource(resourceName) optional

• resourceName is the resource identifier.
• Returns null.

This Lever method is invoked by the Lever OS subsystem when a resource is unlinked from the instance handling this call. The CloseResource invokation is guaranteed to be called after all invokations belonging to that resource are called.

🚧

Important

There is no guarantee that CloseResource is called every time. It is possible that the instance crashes or that Lever OS closes the instance before it has the opportunity to handle CloseResource calls.