Mapping
The Mapping is one of the most exciting features of WebSemaphore and we are still exploring its uses and implications. A semaphore's mapping is a pure javascript function, with other languages upcoming. Leaner than a lambda but more powerful than a template, the little piece of javascript code can be used to:
- Validate the original request input
- Map/enrich the original request
- Avoid additional callback when sending the request to a remote system
- Decide on complex rerouting scenarios
- [upcoming] decide on failover policy
- [upcoming] completely take over the processing and return the result when available
Generative AI Mapping Assistant
To simplify mapping development, we've introduced the AI assistant that can speed up the mapping process. Backed by an LLM the assistant will generate a barebones mapping based on the input and output you provide. We expect the assistant to help you significantly cut down mapping development time. However we advise keeping a human eye on the code the assistant is suggesting.
Mapping handler
The mapping is a piece of code that must have a handler function defined.
The rest of the code may provide constants and any other valid code.
The handler function is accepting two parameters:
- message
string | object- the original message sent by the semaphore requestor. If the message is a json it will be parsed and passed as an object. Otherwise message is a string. - context
object- see below
return value - object - see below
Mapping context object
| Property | Description | Type | Possible Values |
|---|---|---|---|
| routing | Routing information for the inbound request. | object | |
| routing.transport | The transport type for the routing. | enum | - 'websockets' |
| - 'https' | |||
| routing.remoteId | The specific websockets session that requested the | string | |
| routing (applicable only for 'websockets' transport). | |||
| semaphore | Semaphore information. | object | |
| semaphore.id | The ID of the semaphore. | string | |
| semaphore.channelId | The ID of the channel over which the request was sent. | string | |
| semaphore.queueId | The ID of the queue (depends on semaphore.maxValueScope). | string | |
| semaphore.owner | The owner of the semaphore. | string | |
| semaphore.lockId | The lock ID. | string | |
| semaphore.lockValue | The lock value during the mapping. | string |
Example:
Mapping return value
The mapping handler returns an object containing the .body property which may be any valid Javascript object or primitive. Non-primitive values will be serizlied to JSON. Future additional properties may expand the range of mapping applications.
Example:
Mapping execution environment
The mapping is executed in an isolated environment and has only access to message and context as above, and to the standard javascript
globals such as JSON.stringify / JSON.parse.
Due to security constraints under investigation io calls such as fetch are not allowed.
For mutual security of the customers, the hanler's global scope is completely
isolated.
Mapping execution duraiton
The max runtime for the mapping is configured by the mapping.maxExecutionTime in seconds. Higher plans will allow for more runtime.
Features under review / upcoming
-
Secrets - It is clear to us that a secrets store is necessary when security meets custom code. We are planning a secrets store that will allow to separate access to secrets from semaphore configuration and mapping handler code and make the secret values available only during the runtime of the handler.
-
Other languages - While javascript is great, we would like WebSemaphore to be as language agnostic. Please contact us if you require support for a specific language for your use case.
-
Remote access - While the instinct is to block io calls altogether, this might be a desired feature to access e.g. live reference information for improved mapping. We are considering the cost and security implications and are looking for safe ways to implement such features.
