chronos, docs: Add job variable support (#252)

chronos/App.cpp

@@ -1,6 +1,6 @@
 /*
  * chronos, the cron-job.org execution daemon
- * Copyright (C) 2017 Patrick Schlangen <[email protected]>
+ * Copyright (C) 2017-2024 Patrick Schlangen <[email protected]>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -368,7 +368,7 @@ void App::processJobsForTimeZone(int hour, int minute, int month, int mday, int
 				requestTimeout = groupRequestTimeout;
 			}
 
-			HTTPRequest *req = HTTPRequest::fromURL(row[0], atoi(row[10]), maxSize, requestTimeout);
+			HTTPRequest *req = HTTPRequest::fromURL(Utils::replaceVariables(row[0]), atoi(row[10]), maxSize, requestTimeout);
 			req->result->maxFailures 	= maxFailures;
 			req->result->jobID 			= atoi(row[1]);
 			req->result->datePlanned	= (uint64_t)timestamp * 1000;
@@ -392,13 +392,13 @@ void App::processJobsForTimeZone(int hour, int minute, int month, int mday, int
 					row[1]);
 				while(MYSQL_ROW row = headerRes->fetchRow())
 				{
-					req->requestHeaders.push_back({ std::string(row[0]), std::string(row[1]) });
+					req->requestHeaders.push_back({ std::string(row[0]), Utils::replaceVariables(std::string(row[1])) });
 				}
 			}
 
 			if(row[13] != NULL)
 			{
-				req->requestBody	= row[13];
+				req->requestBody	= Utils::replaceVariables(std::string(row[13]));
 			}
 
 			req->result->title		= row[14];

chronos/Utils.cpp

@@ -1,6 +1,6 @@
 /*
  * chronos, the cron-job.org execution daemon
- * Copyright (C) 2017 Patrick Schlangen <[email protected]>
+ * Copyright (C) 2017-2024 Patrick Schlangen <[email protected]>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -12,7 +12,10 @@
 #include "Utils.h"
 
 #include <algorithm>
+#include <ctime>
+#include <functional>
 #include <iostream>
+#include <random>
 #include <sstream>
 #include <string>
 
@@ -61,7 +64,7 @@ void Utils::replace(std::string &str, const std::string &search, const std::stri
 	while((pos = str.find(search, pos)) != std::string::npos)
 	{
 		str.replace(pos, search.length(), repl);
-		pos += search.length();
+		pos += repl.length();
 	}
 }
 
@@ -226,3 +229,64 @@ Utils::Subnet::Subnet(const std::string &cidrNotation)
 	this->netmask = htonl(0xFFFFFFFF << (32 - nBits));
 	this->maskedAddress = ::inet_addr(addressString.c_str()) & this->netmask;
 }
+
+std::string Utils::generateUuid4()
+{
+	static const char HEX_CHARS[] = "0123456789abcdef";
+	static_assert(sizeof(HEX_CHARS) == 16+1, "HEX_CHARS has unexpected size!");
+
+	static thread_local std::mt19937 rng{std::random_device{}()};
+	std::uniform_int_distribution<> dist(0, 15);
+
+	std::string res(36, '-');
+	res[14] = '4';
+	for(std::size_t i = 0; i < 36; ++i)
+	{
+		if (i != 8 && i != 13 && i != 14 && i != 18 && i != 19 && i != 23)
+		{
+			res[i] = HEX_CHARS[dist(rng)];
+		}
+		else if (i == 19)
+		{
+			res[i] = HEX_CHARS[(dist(rng) & 0x3) | 0x8];
+		}
+	}
+	return res;
+}
+
+std::string Utils::replaceVariables(const std::string &in)
+{
+	static const std::string VAR_PREFIX = "%cjo:";
+
+	static const std::unordered_map<std::string, std::function<std::string()>> VARIABLES =
+	{
+		{ "%cjo:unixtime%", [] () { return std::to_string(static_cast<uint64_t>(::time(nullptr))); } },
+		{ "%cjo:uuid4%", [] () { return Utils::generateUuid4(); } },
+	};
+
+	std::string res = in;
+	std::size_t pos = 0;
+	while((pos = res.find(VAR_PREFIX, pos)) != std::string::npos)
+	{
+		bool varMatched = false;
+
+		for(const auto &var : VARIABLES)
+		{
+			if(res.substr(pos, var.first.size()) == var.first)
+			{
+				std::string repl = var.second();
+				res.replace(pos, var.first.size(), repl);
+				pos += repl.size();
+				varMatched = true;
+				break;
+			}
+		}
+
+		if(!varMatched)
+		{
+			pos += VAR_PREFIX.size();
+		}
+	}
+
+	return res;
+}

chronos/Utils.h

@@ -37,6 +37,8 @@ namespace Chronos
 		std::string toLower(const std::string &str);
 		std::vector<std::string> split(const std::string &str, char delimiter);
 		std::string formatString(const std::string &in, const std::unordered_map<char, std::string> &arguments);
+		std::string replaceVariables(const std::string &in);
+		std::string generateUuid4();
 
 		class Subnet
 		{

docs/source/creating-cron-jobs.rst

@@ -0,0 +1,21 @@
+Creating cron jobs
+==================
+
+Cron job variables
+------------------
+In the URL, header values and request body of your cron jobs, you can use special variables. Those special
+variables will be replaced with a corresponding value each time cron-job.org executes your job.
+
+Supported variables
+^^^^^^^^^^^^^^^^^^^
+The following variables are supported by cron-job.org:
+
+================    ========================================================== ===============
+Variable            Description                                                Example
+================    ========================================================== ===============
+%cjo:unixtime%      Current unix timestamp                                     ``1722623610``
+%cjo:uuid4%         A UUID v4 unique identifier (not for cryptographic usage)  ``bd901c8b-11ea-431c-9311-90348e9b3a7f``
+================    ========================================================== ===============
+
+Using a variable multiple times will cause the corresponding value to be re-generated for each occurence of
+the variable. For example, using the ``%cjo:uuid4%`` variable twice will produce two different UUIDs.

docs/source/index.rst

@@ -5,6 +5,7 @@ cron-job.org Documentation
    :maxdepth: 2
    :caption: Contents:
 
+   creating-cron-jobs
    rest-api
 
 Indices and tables