add semantic parsing and normalization support

Author: modelorona

README.md

@@ -174,6 +174,9 @@ Returns a `ConnparseAddress` or throws an `Error`.
 
 Returns a `ParseResult`, but `value` is a stable normalized object instead of a
 faithful raw parse object. Equivalent inputs produce the same normalized JSON.
+It also includes an optional `semantic` block with provider-normalized field
+values that consumers can map onto forms without re-implementing provider
+aliases.
 
 Use `parse()` when you need to preserve the exact original input in `raw`. Use
 `parseNormalize()` when you need dedupe keys, config comparison, cache keys, or
@@ -208,7 +211,16 @@ Both return the same normalized `value`:
   "options": {},
   "raw": "postgres://localhost/app?application_name=myapp&sslmode=require",
   "safe": "postgres://localhost/app?application_name=myapp&sslmode=require",
-  "canonical": "postgres://localhost/app?application_name=myapp&sslmode=require"
+  "canonical": "postgres://localhost/app?application_name=myapp&sslmode=require",
+  "semantic": {
+    "provider": "postgres",
+    "fields": {
+      "ssl_mode": "required"
+    },
+    "consumed": {
+      "query": ["sslmode"]
+    }
+  }
 }
 ```
 

packages/go/builtin_definitions.go

@@ -231,7 +231,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("database", false),
                 new Definition.Rule("object_path", false),
                 map(entry("password", true), entry("username", true)),
-                queryRules(queryRule("createDatabaseIfNotExist", new Definition.QueryRule("boolean", List.of())), queryRule("database", new Definition.QueryRule("string", List.of())), queryRule("debug", new Definition.QueryRule("boolean", List.of())), queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("readonly", new Definition.QueryRule("number", List.of())), queryRule("ssl", new Definition.QueryRule("boolean", List.of())), queryRule("sslmode", new Definition.QueryRule("string", List.of())), queryRule("user", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("createDatabaseIfNotExist", new Definition.QueryRule("boolean", List.of())), queryRule("database", new Definition.QueryRule("string", List.of())), queryRule("debug", new Definition.QueryRule("boolean", List.of())), queryRule("httpProtocol", new Definition.QueryRule("string", List.of("http", "https"))), queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("readonly", new Definition.QueryRule("number", List.of())), queryRule("ssl", new Definition.QueryRule("boolean", List.of())), queryRule("sslmode", new Definition.QueryRule("string", List.of("disable", "require", "verify-ca", "verify-full"))), queryRule("user", new Definition.QueryRule("string", List.of()))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(),
                 new Definition.RedactionRule(List.of("username"), List.of("password"))
@@ -407,7 +407,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("index", false),
                 new Definition.Rule("api_path", false),
                 map(entry("api_key", true), entry("password", true), entry("token", true), entry("username", true)),
-                queryRules(queryRule("api_key", new Definition.QueryRule("string", List.of())), queryRule("apiKey", new Definition.QueryRule("string", List.of())), queryRule("token", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("api_key", new Definition.QueryRule("string", List.of())), queryRule("token", new Definition.QueryRule("string", List.of()))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(),
                 new Definition.RedactionRule(List.of("username"), List.of("password", "api_key", "apiKey", "token"))
@@ -519,7 +519,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("database", false),
                 new Definition.Rule("object_path", false),
                 map(entry("password", true), entry("username", true)),
-                queryRules(queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("sslMode", new Definition.QueryRule("string", List.of("disable", "trust", "verify-ca", "verify-full"))), queryRule("user", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("allowCleartextPasswords", new Definition.QueryRule("boolean", List.of())), queryRule("loc", new Definition.QueryRule("string", List.of())), queryRule("parseTime", new Definition.QueryRule("boolean", List.of())), queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("sslMode", new Definition.QueryRule("string", List.of("disable", "trust", "verify-ca", "verify-full"))), queryRule("user", new Definition.QueryRule("string", List.of()))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(),
                 new Definition.RedactionRule(List.of("username"), List.of("password"))
@@ -631,7 +631,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("database", false),
                 new Definition.Rule("object_path", false),
                 map(entry("password", true), entry("username", true)),
-                queryRules(queryRule("auth-method", new Definition.QueryRule("string", List.of("AUTO", "MYSQL41", "SHA256_MEMORY", "FROM_CAPABILITIES", "FALLBACK", "PLAIN"))), queryRule("charset", new Definition.QueryRule("string", List.of())), queryRule("get-server-public-key", new Definition.QueryRule("boolean", List.of())), queryRule("schema", new Definition.QueryRule("string", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("ssl-ca", new Definition.QueryRule("string", List.of())), queryRule("ssl-capath", new Definition.QueryRule("string", List.of())), queryRule("ssl-cert", new Definition.QueryRule("string", List.of())), queryRule("ssl-cipher", new Definition.QueryRule("string", List.of())), queryRule("ssl-crl", new Definition.QueryRule("string", List.of())), queryRule("ssl-crlpath", new Definition.QueryRule("string", List.of())), queryRule("ssl-key", new Definition.QueryRule("string", List.of())), queryRule("ssl-mode", new Definition.QueryRule("string", List.of("DISABLED", "PREFERRED", "REQUIRED", "VERIFY_CA", "VERIFY_IDENTITY"))), queryRule("tls-version", new Definition.QueryRule("string", List.of())), queryRule("tls-versions", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("allowCleartextPasswords", new Definition.QueryRule("boolean", List.of())), queryRule("auth-method", new Definition.QueryRule("string", List.of("AUTO", "MYSQL41", "SHA256_MEMORY", "FROM_CAPABILITIES", "FALLBACK", "PLAIN"))), queryRule("charset", new Definition.QueryRule("string", List.of())), queryRule("get-server-public-key", new Definition.QueryRule("boolean", List.of())), queryRule("loc", new Definition.QueryRule("string", List.of())), queryRule("parseTime", new Definition.QueryRule("boolean", List.of())), queryRule("schema", new Definition.QueryRule("string", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("ssl-ca", new Definition.QueryRule("string", List.of())), queryRule("ssl-capath", new Definition.QueryRule("string", List.of())), queryRule("ssl-cert", new Definition.QueryRule("string", List.of())), queryRule("ssl-cipher", new Definition.QueryRule("string", List.of())), queryRule("ssl-crl", new Definition.QueryRule("string", List.of())), queryRule("ssl-crlpath", new Definition.QueryRule("string", List.of())), queryRule("ssl-key", new Definition.QueryRule("string", List.of())), queryRule("ssl-mode", new Definition.QueryRule("string", List.of("DISABLED", "PREFERRED", "REQUIRED", "VERIFY_CA", "VERIFY_IDENTITY"))), queryRule("tls-version", new Definition.QueryRule("string", List.of())), queryRule("tls-versions", new Definition.QueryRule("string", List.of()))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(),
                 new Definition.RedactionRule(List.of("username"), List.of("password", "ssl-ca", "ssl-capath", "ssl-cert", "ssl-cipher", "ssl-crl", "ssl-crlpath", "ssl-key"))
@@ -695,7 +695,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("index", false),
                 new Definition.Rule("api_path", false),
                 map(entry("api_key", true), entry("password", true), entry("token", true), entry("username", true)),
-                queryRules(queryRule("api_key", new Definition.QueryRule("string", List.of())), queryRule("apiKey", new Definition.QueryRule("string", List.of())), queryRule("token", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("api_key", new Definition.QueryRule("string", List.of())), queryRule("token", new Definition.QueryRule("string", List.of()))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(entry("compatible_with", "elasticsearch")),
                 new Definition.RedactionRule(List.of("username"), List.of("password", "api_key", "apiKey", "token"))
@@ -727,7 +727,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("database", true),
                 new Definition.Rule("object_path", false),
                 map(entry("password", true), entry("username", true)),
-                queryRules(queryRule("application_name", new Definition.QueryRule("string", List.of())), queryRule("connect_timeout", new Definition.QueryRule("number", List.of())), queryRule("host", new Definition.QueryRule("string", List.of())), queryRule("hostaddr", new Definition.QueryRule("string", List.of())), queryRule("options", new Definition.QueryRule("string", List.of())), queryRule("passfile", new Definition.QueryRule("string", List.of())), queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("port", new Definition.QueryRule("string", List.of())), queryRule("require_auth", new Definition.QueryRule("string", List.of())), queryRule("service", new Definition.QueryRule("string", List.of())), queryRule("sslcert", new Definition.QueryRule("string", List.of())), queryRule("sslkey", new Definition.QueryRule("string", List.of())), queryRule("sslmode", new Definition.QueryRule("string", List.of("disable", "allow", "prefer", "require", "verify-ca", "verify-full"))), queryRule("sslrootcert", new Definition.QueryRule("string", List.of())), queryRule("target_session_attrs", new Definition.QueryRule("string", List.of("any", "read-write", "read-only", "primary", "standby", "prefer-standby")))),
+                queryRules(queryRule("application_name", new Definition.QueryRule("string", List.of())), queryRule("connect_timeout", new Definition.QueryRule("number", List.of())), queryRule("host", new Definition.QueryRule("string", List.of())), queryRule("hostaddr", new Definition.QueryRule("string", List.of())), queryRule("options", new Definition.QueryRule("string", List.of())), queryRule("passfile", new Definition.QueryRule("string", List.of())), queryRule("password", new Definition.QueryRule("string", List.of())), queryRule("port", new Definition.QueryRule("string", List.of())), queryRule("require_auth", new Definition.QueryRule("string", List.of())), queryRule("search_path", new Definition.QueryRule("string", List.of())), queryRule("service", new Definition.QueryRule("string", List.of())), queryRule("sslcert", new Definition.QueryRule("string", List.of())), queryRule("sslkey", new Definition.QueryRule("string", List.of())), queryRule("sslmode", new Definition.QueryRule("string", List.of("disable", "allow", "prefer", "require", "verify-ca", "verify-full"))), queryRule("sslrootcert", new Definition.QueryRule("string", List.of())), queryRule("target_session_attrs", new Definition.QueryRule("string", List.of("any", "read-write", "read-only", "primary", "standby", "prefer-standby")))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(),
                 new Definition.RedactionRule(List.of("username"), List.of("password", "passfile", "sslcert", "sslkey", "sslrootcert"))
@@ -935,7 +935,7 @@ static List<Definition> builtInDefinitions() {
                 new Definition.Rule("database", false),
                 new Definition.Rule("object_path", false),
                 map(entry("password", true), entry("username", true)),
-                queryRules(queryRule("charset", new Definition.QueryRule("string", List.of())), queryRule("loc", new Definition.QueryRule("string", List.of())), queryRule("parseTime", new Definition.QueryRule("boolean", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("ssl-mode", new Definition.QueryRule("string", List.of()))),
+                queryRules(queryRule("allowCleartextPasswords", new Definition.QueryRule("boolean", List.of())), queryRule("charset", new Definition.QueryRule("string", List.of())), queryRule("loc", new Definition.QueryRule("string", List.of())), queryRule("parseTime", new Definition.QueryRule("boolean", List.of())), queryRule("ssl", new Definition.QueryRule("string", List.of())), queryRule("ssl-mode", new Definition.QueryRule("string", List.of("DISABLED", "PREFERRED", "REQUIRED", "VERIFY_CA", "VERIFY_IDENTITY")))),
                 new Definition.ValidationRule(true, new Definition.PortRange(1L, 65535L)),
                 map(entry("compatible_with", "mysql")),
                 new Definition.RedactionRule(List.of("username"), List.of("password"))

packages/java/src/main/java/com/clidey/connparse/BuiltInDefinitions.java

@@ -91,13 +91,23 @@ logger.info({ connection: result.value.safe });
 ```
 
 Use `parseNormalize()` when you need a stable identity for dedupe, cache keys,
-or config comparison.
+or config comparison. It also returns provider-normalized semantic fields for
+consumers that want stable form values instead of provider-specific query keys.
 
 ```ts
 import { parseNormalize } from '@clidey/connparse';
 
-parseNormalize('postgresql://LOCALHOST:5432/app?sslmode=require').value.canonical;
-// "postgres://localhost/app?sslmode=require"
+const result = parseNormalize('postgresql://LOCALHOST:5432/app?sslmode=require&search_path=tenant_a');
+
+result.value.canonical;
+// "postgres://localhost/app?search_path=tenant_a&sslmode=require"
+
+result.value.semantic;
+// {
+//   provider: 'postgres',
+//   fields: { ssl_mode: 'required', search_path: 'tenant_a' },
+//   consumed: { query: ['search_path', 'sslmode'] }
+// }
 ```
 
 Use `provider` when the string does not clearly identify the source type.