pgsqlarbiter 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12,25 +12,49 @@ module Pgsqlarbiter
12
12
  # @return [Set<Symbol>] the set of valid statement type symbols
13
13
  VALID_STATEMENT_TYPES = Set[:select, :insert, :update, :delete, :merge, :values].freeze
14
14
 
15
+ # @return [Schema] the tables and columns that exist in the database
16
+ attr_reader :schema
15
17
  # @return [Set<Symbol>] allowed statement types
16
18
  attr_reader :allowed_statement_types
17
19
  # @return [Set<String>] allowed table and view names
18
20
  attr_reader :allowed_tables
21
+ # @return [Hash{String => Symbol, Set<String>}] for each allowed table,
22
+ # +:all+ or the set of allowed column names
23
+ attr_reader :allowed_columns
19
24
  # @return [Set<String>] allowed function names
20
25
  attr_reader :allowed_functions
26
+ # @return [Set<String>] allowed type names
27
+ attr_reader :allowed_types
21
28
 
22
29
  # Create a new Arbiter with the given whitelists.
23
30
  #
31
+ # @param schema [Schema] the tables and columns that exist in the database.
32
+ # A table that is not in the schema is always denied
24
33
  # @param allowed_statement_types [Array<Symbol>] allowed statement types. Valid values:
25
34
  # +:select+, +:insert+, +:update+, +:delete+, +:merge+, +:values+
26
- # @param allowed_tables [Array<String>] allowed table and view names
35
+ # @param allowed_tables [Array<String>, Hash{String => Symbol, Array<String>}] allowed
36
+ # table and view names. A Hash restricts columns: each value is +:all+ or the list
37
+ # of column names that may be used, whether read or written. A table with a column
38
+ # list cannot be used with +*+, a whole-row reference, +NATURAL JOIN+ or an
39
+ # +INSERT+ without a column list; queries must name the columns they use
27
40
  # @param allowed_functions [Array<String>, Set<String>] allowed function names
28
41
  # (default: {Pgsqlarbiter::DEFAULT_QUERY_FUNCTIONS})
29
- # @raise [ArgumentError] if any statement type is not in {VALID_STATEMENT_TYPES}
30
- def initialize(allowed_statement_types:, allowed_tables:, allowed_functions: Pgsqlarbiter::DEFAULT_QUERY_FUNCTIONS)
42
+ # @param allowed_types [Array<String>, Set<String>] allowed type names for casts,
43
+ # typed literals and column definition lists
44
+ # (default: {Pgsqlarbiter::DEFAULT_QUERY_TYPES})
45
+ # @raise [ArgumentError] if any statement type is not in {VALID_STATEMENT_TYPES}, or
46
+ # an allowed table or column is not in the schema
47
+ def initialize(schema:, allowed_statement_types:, allowed_tables:,
48
+ allowed_functions: Pgsqlarbiter::DEFAULT_QUERY_FUNCTIONS,
49
+ allowed_types: Pgsqlarbiter::DEFAULT_QUERY_TYPES)
50
+ raise ArgumentError, "schema must be a Pgsqlarbiter::Schema" unless schema.is_a?(Schema)
51
+
52
+ @schema = schema
31
53
  @allowed_statement_types = validate_statement_types(allowed_statement_types)
32
- @allowed_tables = Set.new(allowed_tables).freeze
54
+ @allowed_columns = validate_tables(allowed_tables)
55
+ @allowed_tables = Set.new(@allowed_columns.keys).freeze
33
56
  @allowed_functions = Set.new(allowed_functions).freeze
57
+ @allowed_types = Set.new(allowed_types).freeze
34
58
  end
35
59
 
36
60
  # Judge a SQL query against this arbiter's rules, returning a {Verdict} that
@@ -39,30 +63,45 @@ module Pgsqlarbiter
39
63
  # @param sql [String] the SQL query to judge
40
64
  # @return [Verdict] detailed result with {Verdict#allowed?}, individual check
41
65
  # results, and {Verdict#reasons}
42
- # @raise [ParseError] if the SQL cannot be parsed
66
+ # @raise [LexError] if the SQL cannot be tokenized
67
+ # @raise [ParseError] if the SQL is not valid, supported syntax
68
+ # @raise [UnresolvedNameError] if a column or table alias cannot be resolved
43
69
  # @raise [MultipleStatementsError] if the SQL contains more than one statement
44
70
  # @raise [DisallowedStatementError] if the statement type is not a supported DML type
45
71
  def judge(sql)
46
- result = Pgsqlarbiter.analyze(sql)
47
- stmt_ok = @allowed_statement_types.include?(result.statement_type)
48
- bad_tables = result.tables.reject { |t| @allowed_tables.include?(t) }.freeze
72
+ result = Pgsqlarbiter.analyze(sql, schema: @schema)
73
+ bad_statement_types = result.statement_types.reject { |t| @allowed_statement_types.include?(t) }.freeze
74
+ bad_tables = result.tables.reject { |t| @allowed_columns.key?(t) }.freeze
75
+ # Columns of a table that is not allowed are covered by the table itself.
76
+ bad_columns = result.columns.reject do |c|
77
+ table, _, column = c.rpartition(".")
78
+ allowed = @allowed_columns[table]
79
+ allowed.nil? || allowed == :all || allowed.include?(column)
80
+ end.freeze
49
81
  bad_functions = result.functions.reject { |f| @allowed_functions.include?(f) }.freeze
82
+ bad_types = result.types.reject { |t| @allowed_types.include?(t) }.freeze
50
83
 
51
84
  Verdict.new(
52
- allowed: stmt_ok && bad_tables.empty? && bad_functions.empty?,
53
- statement_type_allowed: stmt_ok,
85
+ allowed: bad_statement_types.empty? && bad_tables.empty? && bad_columns.empty? &&
86
+ bad_functions.empty? && bad_types.empty?,
87
+ statement_type_allowed: bad_statement_types.empty?,
54
88
  statement_type: result.statement_type,
89
+ disallowed_statement_types: bad_statement_types,
55
90
  disallowed_tables: bad_tables,
56
- disallowed_functions: bad_functions
91
+ disallowed_columns: bad_columns,
92
+ disallowed_functions: bad_functions,
93
+ disallowed_types: bad_types
57
94
  )
58
95
  end
59
96
 
60
97
  # Check whether a SQL query is allowed under this arbiter's rules.
61
98
  #
62
99
  # @param sql [String] the SQL query to check
63
- # @return [Boolean] +true+ if the statement type, all tables, and all functions
64
- # are within the configured whitelists
65
- # @raise [ParseError] if the SQL cannot be parsed
100
+ # @return [Boolean] +true+ if every statement type, table, column, function and type
101
+ # is within the configured whitelists
102
+ # @raise [LexError] if the SQL cannot be tokenized
103
+ # @raise [ParseError] if the SQL is not valid, supported syntax
104
+ # @raise [UnresolvedNameError] if a column or table alias cannot be resolved
66
105
  # @raise [MultipleStatementsError] if the SQL contains more than one statement
67
106
  # @raise [DisallowedStatementError] if the statement type is not a supported DML type
68
107
  def allow?(sql)
@@ -71,6 +110,34 @@ module Pgsqlarbiter
71
110
 
72
111
  private
73
112
 
113
+ # A table or column that is whitelisted but missing from the schema is a
114
+ # mistake in one or the other; refusing to start is better than silently
115
+ # never allowing it.
116
+ def validate_tables(tables)
117
+ tables = tables.to_h { |table| [table, :all] } unless tables.is_a?(Hash)
118
+ allowed = {}
119
+ tables.each do |table, columns|
120
+ table = table.to_s
121
+ raise ArgumentError, "allowed table #{table.inspect} is not in the schema" unless @schema.table?(table)
122
+
123
+ allowed[table] =
124
+ if columns == :all
125
+ :all
126
+ elsif columns.respond_to?(:to_ary) || columns.is_a?(Set)
127
+ columns = Set.new(columns.map(&:to_s))
128
+ unknown = columns.reject { |column| @schema.column?(table, column) }
129
+ unless unknown.empty?
130
+ raise ArgumentError, "allowed column(s) #{unknown.map(&:inspect).join(", ")} of table " \
131
+ "#{table.inspect} are not in the schema"
132
+ end
133
+ columns.freeze
134
+ else
135
+ raise ArgumentError, "allowed columns of #{table.inspect} must be :all or a list of column names"
136
+ end
137
+ end
138
+ allowed.freeze
139
+ end
140
+
74
141
  def validate_statement_types(types)
75
142
  set = Set.new(types)
76
143
  invalid = set - VALID_STATEMENT_TYPES
@@ -7,7 +7,11 @@ module Pgsqlarbiter
7
7
  # cause resource exhaustion (e.g. generate_series) — resource limits should be enforced elsewhere.
8
8
  #
9
9
  # Excluded: functions not used by regular queries such as pg_sleep, set_config, lo_*, pg_advisory_lock,
10
- # pg_notify, sequence functions, and system information functions.
10
+ # pg_notify, sequence functions, and system information functions (including the parenthesis-less
11
+ # ones such as current_user and current_schema).
12
+ #
13
+ # Nothing in this list may execute SQL passed to it as text or resolve an object name passed as
14
+ # text. That is why ts_rewrite, whose two-argument form runs a query, is not here.
11
15
  DEFAULT_QUERY_FUNCTIONS = Set[
12
16
  # -- Aggregate functions --
13
17
  "array_agg", "avg", "bit_and", "bit_or", "bit_xor",
@@ -80,6 +84,8 @@ module Pgsqlarbiter
80
84
  "make_timestamp", "make_timestamptz",
81
85
  "now", "statement_timestamp",
82
86
  "timeofday", "transaction_timestamp",
87
+ "current_date", "current_time", "current_timestamp",
88
+ "localtime", "localtimestamp",
83
89
 
84
90
  # -- Formatting functions --
85
91
  "to_char", "to_date", "to_number", "to_timestamp",
@@ -117,6 +123,8 @@ module Pgsqlarbiter
117
123
  "json_array_elements", "jsonb_array_elements",
118
124
  "json_array_elements_text", "jsonb_array_elements_text",
119
125
  "json_scalar", "jsonb_scalar",
126
+ "json", "json_serialize", "json_exists", "json_query", "json_value",
127
+ "json_objectagg", "json_arrayagg",
120
128
  "json_table",
121
129
 
122
130
  # -- Array functions --
@@ -156,12 +164,12 @@ module Pgsqlarbiter
156
164
  "querytree", "setweight", "strip",
157
165
  "to_tsquery", "to_tsvector",
158
166
  "ts_delete", "ts_filter", "ts_headline", "ts_lexize",
159
- "ts_rank", "ts_rank_cd", "ts_rewrite",
167
+ "ts_rank", "ts_rank_cd",
160
168
  "tsvector_to_array", "websearch_to_tsquery",
161
169
 
162
170
  # -- XML functions --
163
171
  "xmlcomment", "xmlconcat", "xmlexists",
164
- "xmlelement", "xmlforest", "xmlparse", "xmlroot", "xmlserialize",
172
+ "xmlelement", "xmlforest", "xmlparse", "xmlpi", "xmlroot", "xmlserialize",
165
173
  "xmltable",
166
174
  "xpath", "xpath_exists",
167
175
 
@@ -0,0 +1,55 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "set"
4
+
5
+ module Pgsqlarbiter
6
+ # Default set of PostgreSQL types a query may name: in a cast (+x::type+,
7
+ # +CAST(x AS type)+), a typed literal (+type 'text'+), or a column
8
+ # definition list.
9
+ #
10
+ # Types written with SQL-standard keywords are recorded under one canonical
11
+ # name whatever the spelling: +int+ and +integer+ are "integer"; +decimal+,
12
+ # +dec+ and +numeric+ are "numeric"; +char+, +character+ and +nchar+ are
13
+ # "character"; +varchar+ and +character varying+ are "character varying";
14
+ # +timestamp without time zone+ is "timestamp". Every other type is recorded
15
+ # exactly as written, so aliases such as +int4+ and +timestamptz+ are listed
16
+ # separately. Array types are recorded as their element type.
17
+ #
18
+ # Excluded: the object identifier types (regclass, regproc, regtype, ...),
19
+ # which look up catalog objects by name, and oid and name.
20
+ DEFAULT_QUERY_TYPES = Set[
21
+ # -- Numeric --
22
+ "smallint", "integer", "bigint", "int2", "int4", "int8",
23
+ "real", "float", "double precision", "float4", "float8",
24
+ "numeric", "money",
25
+
26
+ # -- Boolean --
27
+ "boolean", "bool",
28
+
29
+ # -- Character and binary --
30
+ "text", "character", "character varying", "bpchar", "bytea",
31
+ "bit", "bit varying", "varbit",
32
+
33
+ # -- Date/time --
34
+ "date", "time", "time with time zone", "timetz",
35
+ "timestamp", "timestamp with time zone", "timestamptz",
36
+ "interval",
37
+
38
+ # -- UUID, JSON, XML --
39
+ "uuid", "json", "jsonb", "jsonpath", "xml",
40
+
41
+ # -- Network --
42
+ "inet", "cidr", "macaddr", "macaddr8",
43
+
44
+ # -- Text search --
45
+ "tsvector", "tsquery",
46
+
47
+ # -- Geometric --
48
+ "point", "line", "lseg", "box", "path", "polygon", "circle",
49
+
50
+ # -- Range and multirange --
51
+ "int4range", "int8range", "numrange", "tsrange", "tstzrange", "daterange",
52
+ "int4multirange", "int8multirange", "nummultirange",
53
+ "tsmultirange", "tstzmultirange", "datemultirange"
54
+ ].freeze
55
+ end
@@ -10,6 +10,11 @@ module Pgsqlarbiter
10
10
  # Raised when the analyzer encounters invalid or unparseable SQL structure.
11
11
  class ParseError < Error; end
12
12
 
13
+ # Raised when a column or a table alias in the query cannot be matched to
14
+ # anything in its FROM clause and the {Schema}. A column that is missing from
15
+ # the schema raises this, as does a reference PostgreSQL itself would reject.
16
+ class UnresolvedNameError < Error; end
17
+
13
18
  # Raised when the SQL contains more than one statement.
14
19
  class MultipleStatementsError < Error; end
15
20