Working with <\/span>CosmosDB JavaScript triggers <\/span><\/em>and <\/span>stored procedures <\/span>can be problematic, especially when your application consists of three or four separate development environments. After you\u2019ve created your function in Azure’s fun built-in notepad, you have to copy and paste the code to each collection in every environment by hand.<\/span><\/p>\n\n\n\n It’s not difficult to imagine the amount of work one has to put in syncing this code across every tier, not to mention that this approach is prone to errors and often results in inconsistencies; it is quite easy to forget to propagate the changes to each environment.<\/span><\/p>\n\n\n\n Sometimes your application is branded for different clients. 2 apps in 4 environments with separate databases, each with 3 triggers, 3 stored procedures; you end up copying and pasting the functions roughly 42 times, not to mention logging into different accounts in between. Yikes!<\/span><\/p>\n\n\n\n Furthermore, we don’t want functions to just lie around in the <\/span>Azure Portal<\/span><\/em>. Ideally, we would want to keep them in an external repository, safe from frequent collection deletions and migrations, particularly in the early stages of development.<\/span><\/p>\n\n\n\n The solution for all this madness is putting to work the <\/span>GitLab CI<\/span><\/em>! With a bit of help from NodeJS.<\/span><\/p>\n\n\n\n With CI<\/abbr> configured for our task, we’re not only able to effortlessly deploy the code to all environments via the <\/span>CosmosDB<\/span><\/em> REST API, but we can also use Babel.js to \u201cminify\u201d the code and make it faster as a result (which matters greatly at scale).<\/span><\/p>\n\n\n\n First things first, let’s take care of Package.json and its dependencies<\/b>:<\/p>\n\n\n\n Let\u2019s look at The What we configured above is ready to be executed with one simple command: This command has to be put inside the We start by importing all the required modules to our The and the request body:<\/p>\n\n\n\n Now that we\u2019re done with the easy part, it’s time for some Microsoft wisdom.<\/strong><\/p>\n\n\n\n You\u2019ve probably noticed that weirdly named But fear thou not, for I am with thee. I have been through this shadowy valley, so you don’t have to do it yourself.<\/span><\/p>\n\n\n\n The result of this journey is a token generation function<\/b> that looks like this:<\/span><\/p>\n\n\n\n It’s based on their sample function. Do not modify any of this.<\/strong> It has to have exactly two In the first param we specify the http method we want to use with this particular request.<\/p>\n\n\n\n The second param wasn\u2019t so easy to figure out. After some time, the final thing that worked is a path combined of these elements:<\/p>\n\n\n\n Next, we have another The fourth param, The last parameter is your database\u2019s primary key which is confusingly referred to in the docs as \u201cmaster key\u201d.<\/p>\n\n\n\n The token that we get in return is valid for 15 minutes for this particular resource, plenty of time to do our business. The We are reading the minified file synchronously with the help of the nodeJS file system. It is important to set the encoding to ‘utf-8’.<\/p>\n\n\n\n In the requestBody, the parameter In this snippet, I have provided the name of the procedure in Let’s head to the terminal and say But there is a problem with that and there is a reason why we have named the function Let\u2019s fix that, by adding a condition right after our This time, when we get a response with The hero we need and also deserve<\/span><\/h3>\n\n\n\n
Azure<\/span> CosmosDB <\/span>JS functions: the beginning<\/span><\/h2>\n\n\n\n
The project structure<\/span><\/h3>\n\n\n\n
cosmosdb-functions\n \u2502\n \u251c\u2500\u2500 dist <- Babel destination directory\n \u2502\n \u251c\u2500\u2500 node_modules\n \u2502\n \u251c\u2500\u2500 src\n \u2502 \u251c\u2500\u2500 procedures\n \u2502 \u2514\u2500\u2500 triggers\n \u2502\n .gitignore\n .gitlab-ci.yml\n package.json\n package-lock.json\n synchronizeWithCosmosDB.js<\/code><\/pre>\n\n\n\nPackage.json and its dependencies<\/h3>\n\n\n\n
{\n \"name\": \"cosmosdb-functions\",\n \"version\": \"1.0.0\",\n \"description\": \"Sample CosmosDB triggers and stored procedures\",\n \"scripts\": {\n \"start\": \"babel src --out-dir dist\"\n },\n \"babel\": {\n \"presets\": [\n [\n \"minify\",\n {\n \"removeConsole\": true\n }\n ]\n ],\n \"plugins\": [\n \"babel-plugin-loop-optimizer\"\n ]\n },\n \"devDependencies\": {\n \"@babel\/cli\": \"^7.1.2\",\n \"@babel\/core\": \"^7.1.2\",\n \"babel-preset-minify\": \"^0.5.0\",\n \"babel-plugin-loop-optimizer\": \"^1.4.1\",\n \"crypto\": \"^1.0.1\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"ssh:\/\/git@git.your-git-repo.com:1337\/sample-repo\/cosmosdb-functions.git\"\n }\n}\n<\/code><\/pre>\n\n\n\ndevDependencies<\/code>:<\/p>\n\n\n\nbabel-preset-minify<\/code> will \u201cminify\u201d or “uglify” our code, so the output file will be smaller in size, and babel-plugin-loop-optimizer will transform any map()<\/code> or forEach()<\/code> to normal for loops, also reducing execution times.<\/li>Babel configuration<\/h3>\n\n\n\n
babel<\/code> property in package.json<\/code> contains all the info regarding how Babel should process your source files. There is only one preset declared: minify<\/code>, but with the additional removeConsole<\/code> option which will remove all console.log()<\/code> occurrences in the code during the minification process. Inside the plugins property we declare the loop optimizer.<\/p>\n\n\n\nbabel src --out-dir dist<\/code>. With this command we are telling Babel to get everything from the src<\/code> directory, and put the effects of the transformation into dist<\/code> directory. Easy!<\/p>\n\n\n\nscripts<\/code> property. Later we\u2019ll ask the CI runner to use it.<\/p>\n\n\n\nThe warm-up<\/h3>\n\n\n\n
synchronizeWithCosmosDB.js<\/code> file and then we implement a function for serving all the http requests, using vanilla NodeJS https module.<\/p>\n\n\n\nconst crypto = require('crypto');\nconst fileSystem = require('fs');\nconst https = require('https');\n\nasync function makeRequest(requestOptions, requestBody) {\n return new Promise((resolve, reject) => {\n const request = https.request(requestOptions, (response) => {\n const chunks = [];\n response.on('data', data => {\n chunks.push(data);\n });\n response.on('end', () => {\n let responseBody = Buffer.concat(chunks);\n responseBody = JSON.parse(responseBody);\n resolve(responseBody);\n });\n });\n request.on('error', (error) => {\n reject(error);\n });\n request.write(JSON.stringify(requestBody));\n request.end();\n });\n}<\/code><\/pre>\n\n\n\nhttps<\/code> node module can be a little unintuitive to use, but you don’t really need to know how the makeRequest()<\/code> function works, only that it takes in two parameters:
a request options:<\/p>\n\n\n\nconst procedurePutOptions = {\n hostname: HOSTNAME,\n path: `\/${COLLECTION_RESOURCE_ID}\/sprocs\/${requestBody.id}`,\n method: 'PUT',\n headers: {\n 'x-ms-version': COSMOSDB_API_VERSION,\n 'Content-Type': 'application\/json',\n 'Authorization': authTokenPUT,\n 'x-ms-date': DATE\n }\n};<\/code><\/pre>\n\n\n\nconst requestBody = {\n body: procedure, \/\/ the code processed by babel goes in here\n id: procedureFileName\n};<\/code><\/pre>\n\n\n\n![\"Azure](\"https:\/\/zaven.co\/blog\/wp-content\/uploads\/2018\/11\/image4.gif\")
The main villain<\/span><\/h3>\n\n\n\n
authTokenPUT<\/code> sitting in headers. For some reason, the CosmosDB<\/em> REST API requires a new token for every method and for each single resource you’re trying to modify.<\/span><\/p>\n\n\n\nfunction getAuthorizationToken(httpMethod, resourcePath, resourceType, date, databasePrimaryKey) {\n const params = `${httpMethod.toLowerCase()}\\n${resourceType.toLowerCase()}\\n${resourcePath}\\n${date.toLowerCase()}\\n\\n`;\n\n const key = Buffer.from(databasePrimaryKey, 'base64');\n const body = Buffer.from(params, 'utf8');\n const signature = crypto.createHmac('sha256', key).update(body).digest('base64');\n\n return encodeURIComponent(`type=master&ver=1.0&sig=${signature}`);\n}<\/code><\/pre>\n\n\n\n\\n<\/code> at the end of the params<\/code> string.
How does it work? We don’t need to know that! All that we care about is how to use it:<\/p>\n\n\n\nconst authTokenPUT = getAuthorizationToken(\n 'PUT',\n `${COLLECTION_RESOURCE_ID}\/sprocs\/${requestBody.id}`,\n 'sprocs',\n DATE,\n DATABASE_PRIMARY_KEY\n);<\/code><\/pre>\n\n\n\nCOLLECTION_RESOURCE_ID<\/code>,the path to your collection in following format: dbs\/{database}\/colls\/{collectionName}<\/code> (e.g. dbs\/exampleDB\/colls\/sample_collection<\/code>)<\/li>\/sprocs\/<\/code>, which means stored procedures directory associated with sample_collection<\/li>id<\/code> (the name) of the stored procedure we want to update.<\/li><\/ul>\n\n\n\n\u2019sprocs\u2019<\/code>, which is needed, for some reason. It’s the resourceType<\/code>, and in our case, we will be using two of them: sprocs<\/code> and triggers<\/code>.<\/p>\n\n\n\nDATE<\/code> is the date we generate once as a constant, for all our requests to use. Please notice, that the date has to be exactly the same as the x-ms-date<\/code> in the headers. This fact was also omitted in the docs.<\/p>\n\n\n\n
Now that we have everything we need, let’s try to send our stored procedure to CosmosDB.<\/strong><\/p>\n\n\n\nAzure functions CosmosDB<\/span>: f<\/span>irst call<\/h2>\n\n\n\n
synchronizeWithCosmosDB.js<\/code> now looks like this:<\/p>\n\n\n\nDATABASE_PRIMARY_KEY = 'databaseprimarykeythatendswithtwoequalsigns==';\nCOLLECTION_RESOURCE_ID = 'dbs\/exampleDB\/colls\/sample_collection';\nHOSTNAME = 'sample-account-1.documents.azure.com';\n\nconst COSMOSDB_API_VERSION = '2017-02-22'; \/\/ https:\/\/docs.microsoft.com\/en-us\/rest\/api\/cosmos-db\/ <-latest versions here\nconst PROCEDURES_PATH = '.\/dist\/procedures';\nconst TRIGGERS_PATH = '.\/dist\/triggers';\n\nconst DATE = new Date().toUTCString();\n\ntry {\n\n tryPutProcedure('TestProcedure.js').then(console.log);\n\n} catch (error) {\n console.log(error.message);\n}\n\nasync function tryPutProcedure(procedureFileName) {\n const procedure = fileSystem.readFileSync(`${PROCEDURES_PATH}\/${procedureFileName}`, 'utf8');\n const requestBody = {\n body: procedure,\n id: procedureFileName.replace('.js', '')\n };\n\n const authTokenPUT = getAuthorizationToken(\n 'PUT',\n `${COLLECTION_RESOURCE_ID}\/sprocs\/${requestBody.id}`,\n 'sprocs',\n DATE,\n DATABASE_PRIMARY_KEY\n );\n\n const procedurePutOptions = {\n hostname: HOSTNAME,\n path: `\/${COLLECTION_RESOURCE_ID}\/sprocs\/${requestBody.id}`,\n method: 'PUT',\n headers: {\n 'x-ms-version': COSMOSDB_API_VERSION,\n 'Content-Type': 'application\/json',\n 'Authorization': authTokenPUT,\n 'x-ms-date': DATE\n }\n };\n\n let response = await makeRequest(procedurePutOptions, requestBody);\n\n return response;\n}\n\n\/\/ the makeRequest and getAuthorizationToken functions are somewhere below<\/code><\/pre>\n\n\n\nid<\/code> receives the name of the file minus the file extension – for aesthetics.<\/p>\n\n\n\ntryPutProcedure()<\/code> manually. We\u2019ll take care of this later.<\/p>\n\n\n\nnpm start<\/code>, and then node synchronizeWithCosmosDB<\/code>.
If everything goes right, we should see a result similar to this:<\/p>\n\n\n\n{ body: 'async function testProcedure(a){try{}catch(a){}}',\n id: 'TestProcedure',\n _rid: 'dr4DAMsTT78EAAAAAAAAgA==',\n _self: 'dbs\/dr4DAA==\/colls\/dr4DAMsTT78=\/sprocs\/dr4DAMsTT78EAAAAAAAAgA==\/',\n _etag: '\"00007fd4-0000-0000-0000-5bcf327d0000\"',\n _ts: 1540305533 }<\/code><\/pre>\n\n\n\ntryPutProcedure()<\/code>. When we make a PUT request, we are assuming that the procedure code is already in CosmosDB, and most times this assumption will prove to be true. But sometimes we\u2019ll get a response that looks like this:<\/p>\n\n\n\n{ code: 'NotFound',\n message:\n 'Message: {\"Errors\":[\"Resource Not Found\"]}\\r\\nActivityId: 756b133f-9b2c-40a1-8f26-ea3f9847719a, Request URI: \/apps\/f3d2423f-cec0-4d0f-ba12-5146d90faaa7\/services\/5d583876-e9c2-4794-be01-a5aa1169e7b0\/partitions\/d78876e1-7ad6-4b49\n-aa73-9e1711672df1\/replicas\/131841768030204810p\/, RequestStats: \\r\\nRequestStartTime: 2018-10-24T09:51:49.5582642Z, Number of regions attempted: 1\\r\\n, SDK: Microsoft.Azure.Documents.Common\/2.0.0.0' }<\/code><\/pre>\n\n\n\nmakeRequest()<\/code> call:<\/p>\n\n\n\n\/\/...more code...\/\/\n }\n };\n\n let response = await makeRequest(procedurePutOptions, requestBody);\n\n if (response.code === 'NotFound') {\n response = await postProcedure(requestBody);\n }\n\n return response;\n}<\/code><\/pre>\n\n\n\nNotFound<\/code> status, we\u2019ll be ready. The implementation of postProcedure()<\/code>:<\/p>\n\n\n\nasync function postProcedure(requestBody) {\n const authTokenPOST = getAuthorizationToken(\n 'POST',\n COLLECTION_RESOURCE_ID,\n 'sprocs',\n DATE,\n DATABASE_PRIMARY_KEY\n );\n\n const procedurePostOptions = {\n hostname: HOSTNAME,\n path: `\/${COLLECTION_RESOURCE_ID}\/sprocs`,\n method: 'POST',\n headers: {\n 'x-ms-version': COSMOSDB_API_VERSION,\n 'Content-Type': 'application\/json',\n 'Authorization': authTokenPOST,\n 'x-ms-date': DATE\n }\n };\n\n return makeRequest(procedurePostOptions, requestBody);\n}<\/code><\/pre>\n\n\n\n
![\"\"](\"https:\/\/zaven.co\/blog\/wp-content\/uploads\/2018\/11\/Zrzut-ekranu-2018-11-27-o-15.51.42.png\")
![\"The](\"https:\/\/zaven.co\/blog\/wp-content\/uploads\/2018\/11\/Zrzut-ekranu-2018-11-27-o-15.51.54.png\")