{"id":19387734,"url":"https://github.com/haraka/haraka-config","last_synced_at":"2025-04-23T23:31:23.592Z","repository":{"id":4193307,"uuid":"51191729","full_name":"haraka/haraka-config","owner":"haraka","description":"Haraka config file loader and parser","archived":false,"fork":false,"pushed_at":"2025-01-08T21:26:07.000Z","size":130,"stargazers_count":10,"open_issues_count":1,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-18T21:34:07.433Z","etag":null,"topics":["config","config-loader","file-watchers","haraka"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/haraka-config","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haraka.png","metadata":{"files":{"readme":"README.md","changelog":"Changes.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-06T06:00:54.000Z","updated_at":"2025-01-08T21:25:09.000Z","dependencies_parsed_at":"2022-08-25T06:01:22.255Z","dependency_job_id":null,"html_url":"https://github.com/haraka/haraka-config","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haraka","download_url":"https://codeload.github.com/haraka/haraka-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250531988,"owners_count":21446097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","config-loader","file-watchers","haraka"],"created_at":"2024-11-10T10:10:19.887Z","updated_at":"2025-04-23T23:31:23.573Z","avatar_url":"https://github.com/haraka.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# haraka-config\n\nHaraka config file loader, parser, and watcher.\n\n# Config Files\n\n## Config file type/formats\n\nHaraka's config loader can load several types of configuration files.\n\n- value - load a flat file containing a single value (default)\n- ini - load an ini file\n- json - load a json file\n- hjson - load a hjson file\n- yaml - load a yaml file\n- list - load a flat file containing a list of values\n- data - load a flat file containing a list, keeping comments and whitespace.\n- binary - load a binary file into a Buffer\n\nSee the [File Formats](#file_formats) section below for a more detailed\nexplanation of each of the formats.\n\n# Usage\n\n```js\n// From within a plugin:\nconst cfg = this.config.get(name, [type], [callback], [options])\n```\n\nThis will load the file config/rambling.paths in the Haraka directory.\n\n`name` is not a full path, but a filename in the config/ directory. For example:\n\n```js\nconst cfg = this.config.get('rambling.paths', 'list')\n```\n\n`type` can be any of the types listed above.\n\nIf the file name has an `.ini`, `.json` or `.yaml` suffix,\nthe `type` parameter can be omitted.\n\n`callback` is an optional callback function that will be called when\nan update is detected on the file after the configuration cache has been\nupdated by re-reading the file. Use this to refresh configuration\nvariables within your plugin. Example:\n\n```js\nexports.register = function () {\n  this.loginfo('register called')\n  this.load_my_plugin_ini()\n}\n\nexports.load_my_plugin_ini = function () {\n  this.cfg = this.config.get('my_plugin.ini', () =\u003e {\n    // This closure is run a few seconds after my_plugin.ini changes\n    // Re-run the outer function again\n    this.load_my_plugin_ini()\n  })\n  this.loginfo(`cfg=${JSON.stringify(this.cfg)}`)\n}\n\nexports.hook_connect = function (next, connection) {\n  // this.cfg here will be kept updated\n}\n```\n\nThe `options` object can accepts the following keys:\n\n- `no_watch` (default: false) - prevents Haraka from watching for updates.\n- `no_cache` (default: false) - prevents Haraka from caching the file. The file will be re-read on every call to `config.get`. This is not recommended as config files are read syncronously and will slow down Haraka.\n- `booleans` (default: none) - for .ini files, this allows specifying boolean type keys. Default true or false can be specified.\n\n## \u003ca name=\"overrides\"\u003eDefault Config and Overrides\u003c/a\u003e\n\nThe config loader supports dual config files - a file containing defaults,\nand another user installed file containing overrides. The default configs\nreside:\n\n- Haraka: within the config directory in the Haraka install (where `npm i`\n  installed Haraka)\n- NPM plugins - inside the module/config directory\n\nConfig files with overrides are **always** installed in the Haraka config\ndirectory, which you specified when you ran `haraka -i`.\n\nOverrides work in the following manner:\n\n- For `json`, `ini` and `yaml` config, values are overridden on a deep\n  key by key basis.\n- For every other config format, an override file replaces the entire\n  config.\n- If `smtp.json` or `smtp.yaml` exist, their contents will be loaded before all other config files. You can make use of [JSON Overrides](#json-overrides) here for a single file config.\n\n## Examples\n\n1. a plugin installed as a module (or a core Haraka plugin)\n   loads a `list` config from their own `config/plugin_name` file. That list\n   can be completely overridden by a file called `config/plugin_name` in the\n   Haraka local install directory.\n\n2. a plugin using default config from `config/plugin_name.ini`\n   can be overridden on a key-by-key basis. A default\n   `plugin_name.ini` might contain:\n\n```ini\ntoplevel1=foo\ntoplevel2=bar\n\n[subsection]\nsub1=something\n```\n\nAnd the local `plugin_name.ini` might contain:\n\n```ini\ntoplevel2=blee\n\n[subsection]\nsub2=otherthing\n```\n\nThis would be the equivalent of loading config containing:\n\n```ini\ntoplevel1=foo\ntoplevel2=blee\n\n[subsection]\nsub1=something\nsub2=otherthing\n```\n\nThis allows plugins to ship a default config and users can override\nvalues on a key-by-key basis.\n\n# \u003ca name=\"file_formats\"\u003eFile Formats\u003c/a\u003e\n\n## Ini Files\n\n[INI files](https://en.wikipedia.org/wiki/INI_file) are key=value pairs, with optional [sections]. A typical example:\n\n```ini\nfirst_name=Matt\nlast_name=Sergeant\n\n[job]\ntitle=Senior Principal Software Engineer\nrole=Architect\n\n[projects]\nharaka\nqpsmtpd\nspamassassin\n```\n\nThat produces the following Javascript object:\n\n```js\n{\n    main: {\n        first_name: 'Matt',\n        last_name: 'Sergeant'\n    },\n    job: {\n        title: 'Senior Principal Software Engineer',\n        role: 'Architect'\n    },\n    projects: {\n        haraka: undefined,\n        qpsmtpd: undefined,\n        spamassassin: undefined,\n    }\n}\n```\n\nItems before any `[section]` marker are in the implicit `[main]` section.\n\nSome values on the right hand side of the equals are converted:\n\n- integers are converted to integers\n- floats are converted to floats.\n\nThe key=value pairs support continuation lines using the backslash \"\\\" character.\n\nThe `options` object allows you to specify which keys are boolean:\n\n```js\n{\n  booleans: ['reject', 'some_true_value']\n}\n```\n\nOn the options declarations, key names are formatted as section.key.\nIf the key name does not specify a section, it is presumed to be `[main]`.\n\nDeclaring booleans ensures that values are converted as boolean when parsed, and supports the following options for boolean values:\n\n```\ntrue, yes, ok, enabled, on, 1\n```\n\nAnything else is treated as false.\n\nTo default a boolean as true (when the key is undefined or the config file is\nmissing), prefix the key with +:\n\n```js\n{\n  booleans: ['+reject']\n}\n```\n\nFor completeness the inverse is also allowed:\n\n```js\n{\n  booleans: ['-reject']\n}\n```\n\nLists are supported using this syntax:\n\n```ini\nhosts[] = first_host\nhosts[] = second_host\nhosts[] = third_host\n```\n\nwhich produces this javascript array:\n\n\u003c!-- prettier-ignore --\u003e\n```js\n['first_host', 'second_host', 'third_host']\n```\n\n## Flat Files\n\nFlat files are simply either lists of values separated by \\n or a single value in a file on its own. Qmail or qpsmtpd users will be familiar with this format. Lines starting with '#' and blank lines will be ignored unless the type is specified as 'data', however even then line endings will be stripped.\n\n## JSON Files\n\nThese are as you would expect, and return an object as given in the file.\n\nIf a requested .json or .hjson file does not exist then the same file will be checked for with a .yaml extension and that will be loaded instead. This is done because YAML files are far easier for a human to write.\n\n### \u003ca name=\"json-overrides\"\u003eJSON Overrides\u003c/a\u003e\n\nYou can use JSON, HJSON or YAML files to override any other file by prefixing the outer variable name with a `!` e.g.\n\n```js\n{\n  \"!smtpgreeting\": ['this is line one', 'this is line two'],\n  \"!smtp.ini\": {\n    main: {\n      nodes: 0,\n    },\n    headers: {\n      max_lines: 1000,\n      max_received: 100,\n    },\n  },\n  \"!custom-plugin.yaml\": {\n    secret: 'example',\n  },\n}\n```\n\nIf the config/smtpgreeting wasn't loaded before, then this value would replace it. Since `smtp.json` is always loaded first, it can be used to override existing config files.\n\nNOTE: You must ensure that the data type (e.g. Object, Array or String) for the replaced value is correct. This cannot be done automatically.\n\n## Hjson Files\n\nHjson is a syntax extension to JSON. It is intended to be used like a user interface for humans, to read and edit before passing the JSON data to the machine. That means you can use it to parse JSON files but it is not intended as a replacement.\n\nYou can check [Hjson's homepage](https://hjson.github.io/) to get familiar with it and you can [try out its syntax](https://hjson.github.io/try.html).\n\nMain features:\n\n- Comments\n- Optional quotes\n- Optional commas\n- Heredoc\n\nExample syntax\n\n```hjson\n{\n  # specify rate in requests/second (because comments are helpful!)\n  rate: 1000\n\n  // prefer c-style comments?\n  /* feeling old fashioned? */\n\n  # did you notice that rate does not need quotes?\n  hey: look ma, no quotes for strings either!\n\n  # best of all\n  notice: []\n  anything: ?\n\n  # yes, commas are optional!\n}\n```\n\nNOTE: Hjson can be also replaced by a YAML configuration file. You can find more on this issue under JSON section.\n\n## YAML Files\n\nAs per JSON files above but in YAML format.\n\n# Reloading/Caching\n\nHaraka automatically reloads configuration files, but this only works if whatever is looking at that config re-calls config.get() to retrieve the new config. Providing a callback in the config.get() call is the most efficient method to do this.\n\nConfiguration files are watched for changes using filesystem events which are inexpensive. Due to caching, calling config.get() is normally a lightweight process.\n\nOn Linux/Windows, newly created files that Haraka has tried to read in the past will be noticed immediately and loaded. For other operating systems, it may take up to 60 seconds to load, due to differences between in the kernel APIs for watching files/directories.\n\nHaraka reads a number of configuration files at startup. Any files read in a plugins register() function are read _before_ Haraka drops privileges. Be sure that Haraka's user/group has permission to read these files else Haraka will be unable to update them after changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaka%2Fharaka-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharaka%2Fharaka-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaka%2Fharaka-config/lists"}