namespace ZB.MOM.WW.OtOpcUa.Driver.Sql;
///
/// An immutable snapshot of the parts of a database's catalog the authored tags actually name — the
/// allow-list design §8.1 requires identifiers to come from.
/// This type holds catalog strings only. Every name in it was read back out of
/// / /
/// ; nothing an operator typed is ever stored here. That is what
/// lets hand the planner catalog spellings rather than authored ones, so the
/// identifier text in an emitted query is a string the database gave us.
/// Deliberately partial. Only the schemas/tables the authored tags name are loaded — a
/// driver polling three tables must not enumerate a warehouse's ten thousand. A name absent from this
/// snapshot therefore means "not found when we looked", which is exactly the question the gate
/// asks.
///
public sealed class SqlCatalog
{
private readonly IReadOnlyList _schemas;
/// Canonical schema → canonical table names in it.
private readonly IReadOnlyDictionary> _tablesBySchema;
/// Canonical schema.table → that relation's canonical column names.
private readonly IReadOnlyDictionary> _columnsByTable;
/// Stored procedures per canonical schema — loaded only for schemas a Procedure-mode tag names (lmxopcua#781).
private readonly IReadOnlyDictionary> _routinesBySchema;
/// Constructs a catalog snapshot.
/// The schema an unqualified object name resolves to for this connection.
/// Every schema the connection can see.
/// Canonical schema → its tables/views.
/// Canonical schema.table → its columns.
/// Canonical schema → its stored procedures; null ⇒ none loaded.
internal SqlCatalog(
string defaultSchema,
IReadOnlyList schemas,
IReadOnlyDictionary> tablesBySchema,
IReadOnlyDictionary> columnsByTable,
IReadOnlyDictionary>? routinesBySchema = null)
{
_routinesBySchema = routinesBySchema ?? new Dictionary>(StringComparer.Ordinal);
DefaultSchema = defaultSchema;
_schemas = schemas;
_tablesBySchema = tablesBySchema;
_columnsByTable = columnsByTable;
}
///
/// A catalog that resolves nothing — used when no authored tag needs one (a driver serving only named
/// queries), so Initialize does not issue catalog queries whose answer nothing reads.
///
internal static SqlCatalog Empty { get; } = new(
string.Empty, [],
new Dictionary>(StringComparer.Ordinal),
new Dictionary>(StringComparer.Ordinal));
/// The schema an unqualified authored object name is resolved in.
public string DefaultSchema { get; }
/// Resolves an authored schema name to the catalog's own spelling.
/// The authored schema, or null/blank for the default schema.
/// The catalog's spelling, when resolved.
/// when the schema exists (or the default schema is used).
public bool TryResolveSchema(string? authored, out string canonical)
{
if (string.IsNullOrWhiteSpace(authored))
{
canonical = DefaultSchema;
return true;
}
return TryMatch(_schemas, authored, out canonical);
}
/// Resolves an authored table/view name within a canonical schema.
/// The schema, already resolved through .
/// The authored table or view name.
/// The catalog's spelling, when resolved.
/// when the relation exists in that schema.
public bool TryResolveTable(string canonicalSchema, string authored, out string canonical)
{
canonical = string.Empty;
return _tablesBySchema.TryGetValue(canonicalSchema, out var tables)
&& TryMatch(tables, authored, out canonical);
}
/// Resolves an authored column name within a canonical relation.
/// The resolved schema.
/// The resolved table or view.
/// The authored column name.
/// The catalog's spelling, when resolved.
/// when the column exists on that relation.
public bool TryResolveColumn(
string canonicalSchema, string canonicalTable, string authored, out string canonical)
{
canonical = string.Empty;
return _columnsByTable.TryGetValue(QualifiedKey(canonicalSchema, canonicalTable), out var columns)
&& TryMatch(columns, authored, out canonical);
}
///
/// Resolves an authored procedure name in a canonical schema to the catalog's spelling, by the same
/// exact-then-unique-case-insensitive rule as tables and columns.
///
/// The schema, as returned it.
/// The authored procedure name.
/// The catalog spelling, when this returns true.
/// True when exactly one procedure matches.
public bool TryResolveRoutine(string canonicalSchema, string authored, out string canonical)
{
canonical = string.Empty;
return _routinesBySchema.TryGetValue(canonicalSchema, out var routines)
&& TryMatch(routines, authored, out canonical);
}
/// The dictionary key for a canonical relation.
/// The canonical schema.
/// The canonical table.
/// The composite key.
internal static string QualifiedKey(string schema, string table) => schema + "." + table;
///
/// Matches an authored name against catalog spellings: an exact (ordinal) hit wins, otherwise a
/// unique case-insensitive hit is accepted and its catalog spelling returned.
///
///
/// Why case-insensitive at all. SQL Server's default collation is case-insensitive, so
/// num_value and NUM_VALUE genuinely name the same column and both work today. Matching
/// ordinally would reject configurations that have always been valid — a gate that breaks working
/// deployments is not defence in depth.
/// Why exact-first, and why ambiguity fails. On a case-sensitive collation a
/// relation may legitimately carry both Value and value. Preferring the exact match keeps
/// such a config resolving to what the operator wrote, and refusing to choose between two
/// case-insensitive candidates is the only safe answer — silently picking one would publish a different
/// column's data under the operator's node, which is worse than rejecting the tag.
///
/// The catalog spellings to match against.
/// The authored name.
/// The catalog's spelling, when matched.
/// on an unambiguous match.
internal static bool TryMatch(IReadOnlyList candidates, string authored, out string canonical)
{
foreach (var candidate in candidates)
{
if (!string.Equals(candidate, authored, StringComparison.Ordinal)) continue;
canonical = candidate;
return true;
}
canonical = string.Empty;
var matches = 0;
foreach (var candidate in candidates)
{
if (!string.Equals(candidate, authored, StringComparison.OrdinalIgnoreCase)) continue;
if (++matches > 1)
{
canonical = string.Empty;
return false;
}
canonical = candidate;
}
return matches == 1;
}
}