guardinari 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 695c5943a6900a961d484e6f85093a42a5ce1dd9c3c5922135694158eba58de4
+  data.tar.gz: fa9dbf6e5fed9ca33c5c898db23144107d8dc295750a0fd9bea86d37caf4c5ac
+SHA512:
+  metadata.gz: c1f4601be00b785494de79248df3c3453843682e2b2128b835bfc870b011637c9e61bca692b310285804ad70dabe5b5b0523b0b6f6ed787c0d8f460b551fc96f
+  data.tar.gz: 2ef0c623f59bdaeb23e614f90bde9e66206f67b2a08a83860c7cf7b6738faa3e4907930a39401a50c01be1a68d6ba22cf4c0c78037075f60f869b39e7b864513

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Matthew Eagar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# Guardinari
+
+Guardinari finds [Kaminari](https://github.com/kaminari/kaminari) queries containing broken pagination, that is, queries that have a `LIMIT` and `OFFSET` but no `ORDER BY`.
+
+Kaminari mentions this in its README:
+
+> Kaminari does not add an order to queries. To avoid surprises, you should generally include an order in paginated queries.
+
+However, it's pretty easy in a non-trivial Rails app to wind up with a paginated query that does _not_ have an order-by clause. When this happens, the ordering of results is non-deterministic, and causes surprising behavior.
+
+See, for example:
+
+* https://github.com/kaminari/kaminari/issues/1040
+* https://github.com/kaminari/kaminari/pull/1054
+
+Guardinari implements a simple Flex-based lexer to find broken queries without brittle regular expressions that would be prone to false-positives and false-negatives.
+
+It's written in C because it's ~70x faster than the equivalent `StringScanner`-based parser, written in pure Ruby - fast enough to run in dev, test, _and_ prod if you so desire.
+
+> [!WARNING]
+>
+> Guardinari was written largely as a counter point to Aaron Patterson's [Ruby Outperforms C: Breaking the Catch-22](https://railsatscale.com/2023-08-29-ruby-outperforms-c/) and his [Rails World 2024 Keynote](https://www.youtube.com/watch?v=ZE6F3drGhA8) where he shows that pure Ruby parsers can outperform a C extension.
+>
+> Guardinari _massively_ outperforms the equivalent pure Ruby scanner because it eliminates back-and-forth - The C extension is called _once_, with the entire SQL statement in question; the Flex-based tokenizer performs zero allocations, processes the entire query, and returns a boolean `true`/`false` back to Ruby.
+>
+> This project has never run in a production environment, use with caution.
+
+
+## Installation
+
+```bash
+bundle add guardinari
+```
+
+With Guardinari installed, you can check whether a given query is broken:
+
+```ruby
+# Second argument are bound parametesr
+Guardinari.find_broken_pagination('select * from users limit 10 offset 0', []) # => true
+# or
+Guardinari.find_broken_pagination('select * from users limit ? offset ?', [10, 0]) # => true
+```
+
+To make it useful, you probably want to run _all_ your queries through Guardinari; in Rails, you can do this with an `ActiveSupport::Notifications`:
+
+
+```ruby
+ActiveSupport::Notifications.subscribe('sql.active_record') do |_name, _start, _finish, _id, payload|
+  # "SCHEMA" queries are created by Rails, we can trust that they are correct
+  next if payload[:name] == 'SCHEMA'
+
+  sql = payload[:sql]
+  binds = payload[:binds]
+
+  # Raises a Guardinari::BrokenPagination exception
+  # This exception contains the raw SQL, don't render it to the user in production
+  raise "Broken pagination" if Guardinari.find_broken_pagination(sql, binds)
+
+  # OR, custom handling
+  Rails.logger.error("Broken pagination: #{sql}") if Guardinari.find_broken_pagination?(sql, binds)
+end
+```
+
+## What constitutes "Broken"
+
+A query is considered broken if:
+
+- It is a `SELECT` query
+- It has an explicit `LIMIT` _and_ `OFFSET`...
+  - but _not_ `LIMIT 1 OFFSET 0`*
+- It does _not_ have an `ORDER BY`.
+
+The `LIMIT 1 OFFSET 0` is ignored because sometimes Rails seems to generate these in certain circumstances where there is assumed to be exactly 0 or 1 result.
+
+## Implementation
+
+Guardinari is a C-extension, implementing a (very) simple Flex lexer that supports a very small subset of SQL - enough to prevent false positives that would occur with a pure regex-based solution.
+
+What we want is effectively this:
+
+```
+broken_pagination = query.match?(/select/) && query.match?(/limit/) && query.match?(/offset/) && !query.match?(/order by/)
+```
+
+That is, `SELECT` queries with a limit/offset, but no order.
+
+The above regex produces false positives and false negatives on _many_ types of input:
+
+```sql
+-- It cannot detect broken inner queries
+select * from posts where user_id in (
+    -- this inner query is non-deterministically paginated
+    select id from users limit 10 offset 20
+) order by created_at;
+
+
+-- It matches inside strings
+update posts set body = "select * from users limit 10 offset 0";
+
+-- It cannot handle comments
+/* limit 10 offset 0 */ select * from posts;
+
+```
+
+By implementing a simple lexer for the subset of SQL that we care about, these false-positives and false-negatives are avoided.
+
+Of the _hundreds_ of SQL keywords, Guardinari's lexer is really only aware of the `select`, `limit`, `offset` `order` and `by`, while understanding how to skip comments, single- and double-quoted strings, and how to handle sub-queries.
+
+## Benchmarks
+
+An equivalent pure-Ruby `StringScanner`, with and without YJIT, along side benchmarks for Guardinari's C extension, running against a 500 character long SQL `SELECT` query:
+
+
+

data/Rakefile

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rake/extensiontask"
+
+file "ext/guardinari/guardinari.c" => "ext/guardinari/guardinari.l" do |t|
+  sh "flex -o #{t.name} #{t.source}"
+end
+
+task compile: "ext/guardinari/guardinari.c"
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load("guardinari.gemspec")
+
+Rake::ExtensionTask.new("guardinari", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/guardinari"
+end
+
+task default: %i[clobber compile test rubocop]
+
+desc "Run tests with ASan"
+task test_asan: :clobber do
+  ENV["SANITIZE"] = "1"
+  Rake::Task["compile"].invoke
+
+  asan_lib = `clang -print-file-name=libclang_rt.asan_osx_dynamic.dylib`.strip
+  env = { "DYLD_INSERT_LIBRARIES" => asan_lib }
+  system(env, "ruby", "-Ilib:test", *FileList["test/**/*_test.rb"]) || exit(1)
+end

data/ext/guardinari/Makefile

@@ -0,0 +1,277 @@
+
+SHELL = /bin/sh
+
+# V=0 quiet, V=1 verbose.  other values don't work.
+V = 0
+V0 = $(V:0=)
+Q1 = $(V:1=)
+Q = $(Q1:0=@)
+ECHO1 = $(V:1=@ :)
+ECHO = $(ECHO1:0=@ echo)
+NULLCMD = :
+
+#### Start of system configuration section. ####
+
+srcdir = .
+topdir = /Users/matteagar/.asdf/installs/ruby/3.4.7/include/ruby-3.4.0
+hdrdir = $(topdir)
+arch_hdrdir = /Users/matteagar/.asdf/installs/ruby/3.4.7/include/ruby-3.4.0/arm64-darwin25
+PATH_SEPARATOR = :
+VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
+prefix = $(DESTDIR)/Users/matteagar/.asdf/installs/ruby/3.4.7
+rubysitearchprefix = $(rubylibprefix)/$(sitearch)
+rubyarchprefix = $(rubylibprefix)/$(arch)
+rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
+exec_prefix = $(prefix)
+vendorarchhdrdir = $(vendorhdrdir)/$(sitearch)
+sitearchhdrdir = $(sitehdrdir)/$(sitearch)
+rubyarchhdrdir = $(rubyhdrdir)/$(arch)
+vendorhdrdir = $(rubyhdrdir)/vendor_ruby
+sitehdrdir = $(rubyhdrdir)/site_ruby
+rubyhdrdir = $(includedir)/$(RUBY_VERSION_NAME)
+vendorarchdir = $(vendorlibdir)/$(sitearch)
+vendorlibdir = $(vendordir)/$(ruby_version)
+vendordir = $(rubylibprefix)/vendor_ruby
+sitearchdir = $(sitelibdir)/$(sitearch)
+sitelibdir = $(sitedir)/$(ruby_version)
+sitedir = $(rubylibprefix)/site_ruby
+rubyarchdir = $(rubylibdir)/$(arch)
+rubylibdir = $(rubylibprefix)/$(ruby_version)
+sitearchincludedir = $(includedir)/$(sitearch)
+archincludedir = $(includedir)/$(arch)
+sitearchlibdir = $(libdir)/$(sitearch)
+archlibdir = $(libdir)/$(arch)
+ridir = $(datarootdir)/$(RI_BASE_NAME)
+modular_gc_dir = $(DESTDIR)
+mandir = $(datarootdir)/man
+localedir = $(datarootdir)/locale
+libdir = $(exec_prefix)/lib
+psdir = $(docdir)
+pdfdir = $(docdir)
+dvidir = $(docdir)
+htmldir = $(docdir)
+infodir = $(datarootdir)/info
+docdir = $(datarootdir)/doc/$(PACKAGE)
+oldincludedir = $(DESTDIR)/usr/include
+includedir = $(SDKROOT)$(prefix)/include
+runstatedir = $(localstatedir)/run
+localstatedir = $(prefix)/var
+sharedstatedir = $(prefix)/com
+sysconfdir = $(prefix)/etc
+datadir = $(datarootdir)
+datarootdir = $(prefix)/share
+libexecdir = $(exec_prefix)/libexec
+sbindir = $(exec_prefix)/sbin
+bindir = $(exec_prefix)/bin
+archdir = $(rubyarchdir)
+
+
+CC_WRAPPER = 
+CC = clang
+CXX = clang++
+LIBRUBY = $(LIBRUBY_SO)
+LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
+LIBRUBYARG_SHARED = -l$(RUBY_SO_NAME)
+LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static -framework CoreFoundation $(MAINLIBS)
+empty =
+OUTFLAG = -o $(empty)
+COUTFLAG = -o $(empty)
+CSRCFLAG = $(empty)
+
+RUBY_EXTCONF_H = 
+cflags   = $(hardenflags) -fdeclspec  $(optflags) $(debugflags) $(warnflags)
+cxxflags = 
+optflags = -O3 -fno-fast-math
+debugflags = -ggdb3
+warnflags = -Wall -Wextra -Wextra-tokens -Wdeprecated-declarations -Wdivision-by-zero -Wdiv-by-zero -Wimplicit-function-declaration -Wimplicit-int -Wpointer-arith -Wshorten-64-to-32 -Wwrite-strings -Wold-style-definition -Wmissing-noreturn -Wno-cast-function-type -Wno-constant-logical-operand -Wno-long-long -Wno-missing-field-initializers -Wno-overlength-strings -Wno-parentheses-equality -Wno-self-assign -Wno-tautological-compare -Wno-unused-parameter -Wno-unused-value -Wunused-variable -Wmisleading-indentation -Wundef
+cppflags = 
+CCDLFLAGS = -fno-common
+CFLAGS   = $(CCDLFLAGS) $(cflags) -fno-common -pipe -fvisibility=hidden $(ARCH_FLAG)
+INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir)
+DEFS     = 
+CPPFLAGS =  -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE -D_DARWIN_UNLIMITED_SELECT -D_REENTRANT $(DEFS) $(cppflags)
+CXXFLAGS = $(CCDLFLAGS) -fdeclspec $(ARCH_FLAG)
+ldflags  = -L. -fstack-protector-strong -L/opt/homebrew/Cellar/gmp/6.3.0/lib
+dldflags = -L/opt/homebrew/Cellar/gmp/6.3.0/lib -Wl,-undefined,dynamic_lookup 
+ARCH_FLAG = -arch arm64
+DLDFLAGS = $(ldflags) $(dldflags) $(ARCH_FLAG)
+LDSHARED = $(CC) -dynamic -bundle
+LDSHAREDXX = $(CXX) -dynamic -bundle
+POSTLINK = dsymutil $@ 2>/dev/null; { test -z '$(RUBY_CODESIGN)' || codesign -s '$(RUBY_CODESIGN)' $@; }
+AR = ar
+LD = ld
+EXEEXT = 
+
+RUBY_INSTALL_NAME = $(RUBY_BASE_NAME)
+RUBY_SO_NAME = ruby.3.4
+RUBYW_INSTALL_NAME = 
+RUBY_VERSION_NAME = $(RUBY_BASE_NAME)-$(ruby_version)
+RUBYW_BASE_NAME = rubyw
+RUBY_BASE_NAME = ruby
+
+arch = arm64-darwin25
+sitearch = $(arch)
+ruby_version = 3.4.0
+ruby = $(bindir)/$(RUBY_BASE_NAME)
+RUBY = $(ruby)
+BUILTRUBY = $(bindir)/$(RUBY_BASE_NAME)
+ruby_headers = $(hdrdir)/ruby.h $(hdrdir)/ruby/backward.h $(hdrdir)/ruby/ruby.h $(hdrdir)/ruby/defines.h $(hdrdir)/ruby/missing.h $(hdrdir)/ruby/intern.h $(hdrdir)/ruby/st.h $(hdrdir)/ruby/subst.h $(arch_hdrdir)/ruby/config.h
+
+RM = rm -f
+RM_RF = rm -fr
+RMDIRS = rmdir -p
+MAKEDIRS = /opt/homebrew/bin/gmkdir -p
+INSTALL = /opt/homebrew/bin/ginstall -c
+INSTALL_PROG = $(INSTALL) -m 0755
+INSTALL_DATA = $(INSTALL) -m 644
+COPY = cp
+TOUCH = exit >
+
+#### End of system configuration section. ####
+
+preload = 
+libpath = . $(libdir)
+LIBPATH = -L. -L$(libdir)
+DEFFILE = 
+
+CLEANFILES = mkmf.log
+DISTCLEANFILES = 
+DISTCLEANDIRS = 
+
+extout = 
+extout_prefix = 
+target_prefix = /guardinari
+LOCAL_LIBS = 
+LIBS = $(LIBRUBYARG_SHARED)  -lpthread  
+ORIG_SRCS = guardinari.c
+SRCS = $(ORIG_SRCS) 
+OBJS = guardinari.o
+HDRS = $(srcdir)/scanner.h
+LOCAL_HDRS = 
+TARGET = guardinari
+TARGET_NAME = guardinari
+TARGET_ENTRY = Init_$(TARGET_NAME)
+DLLIB = $(TARGET).bundle
+EXTSTATIC = 
+STATIC_LIB = 
+
+TIMESTAMP_DIR = .
+BINDIR        = $(bindir)
+RUBYCOMMONDIR = $(sitedir)$(target_prefix)
+RUBYLIBDIR    = $(sitelibdir)$(target_prefix)
+RUBYARCHDIR   = $(sitearchdir)$(target_prefix)
+HDRDIR        = $(sitehdrdir)$(target_prefix)
+ARCHHDRDIR    = $(sitearchhdrdir)$(target_prefix)
+TARGET_SO_DIR =
+TARGET_SO     = $(TARGET_SO_DIR)$(DLLIB)
+CLEANLIBS     = $(TARGET_SO) $(TARGET_SO:=.dSYM)
+CLEANOBJS     = $(OBJS) *.bak
+TARGET_SO_DIR_TIMESTAMP = $(TIMESTAMP_DIR)/.sitearchdir.-.guardinari.time
+
+all:    $(DLLIB)
+static: $(STATIC_LIB)
+.PHONY: all install static install-so install-rb
+.PHONY: clean clean-so clean-static clean-rb
+
+clean-static::
+clean-rb-default::
+clean-rb::
+clean-so::
+clean: clean-so clean-static clean-rb-default clean-rb
+		-$(Q)$(RM_RF) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES) .*.time
+
+distclean-rb-default::
+distclean-rb::
+distclean-so::
+distclean-static::
+distclean: clean distclean-so distclean-static distclean-rb-default distclean-rb
+		-$(Q)$(RM) Makefile $(RUBY_EXTCONF_H) conftest.* mkmf.log
+		-$(Q)$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
+		-$(Q)$(RMDIRS) $(DISTCLEANDIRS) 2> /dev/null || true
+
+realclean: distclean
+install: install-so install-rb
+
+install-so: $(DLLIB) $(TARGET_SO_DIR_TIMESTAMP)
+	$(INSTALL_PROG) $(DLLIB) $(RUBYARCHDIR)
+clean-static::
+	-$(Q)$(RM) $(STATIC_LIB)
+install-rb: pre-install-rb do-install-rb install-rb-default
+install-rb-default: pre-install-rb-default do-install-rb-default
+pre-install-rb: Makefile
+pre-install-rb-default: Makefile
+do-install-rb:
+do-install-rb-default:
+pre-install-rb-default:
+	@$(NULLCMD)
+$(TARGET_SO_DIR_TIMESTAMP):
+	$(Q) $(MAKEDIRS) $(@D) $(RUBYARCHDIR)
+	$(Q) $(TOUCH) $@
+
+site-install: site-install-so site-install-rb
+site-install-so: install-so
+site-install-rb: install-rb
+
+.SUFFIXES: .c .m .cc .mm .cxx .cpp .o .S
+
+.cc.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cc.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.mm.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.mm.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.cxx.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cxx.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.cpp.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.cpp.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.c.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.c.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+.m.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+.m.S:
+	$(ECHO) translating $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -S $(CSRCFLAG)$<
+
+$(TARGET_SO): $(OBJS) Makefile
+	$(ECHO) linking shared-object guardinari/$(DLLIB)
+	-$(Q)$(RM) $(@)
+	$(Q) $(LDSHARED) -o $@ $(OBJS) $(LIBPATH) $(DLDFLAGS) $(LOCAL_LIBS) $(LIBS)
+	$(Q) $(POSTLINK)
+
+
+
+###
+all: guardinari.c
+
+guardinari.c: guardinari.l
+	flex -o guardinari.c guardinari.l

data/ext/guardinari/depend

@@ -0,0 +1,4 @@
+all: guardinari.c
+
+guardinari.c: guardinari.l
+	flex -o guardinari.c guardinari.l

data/ext/guardinari/extconf.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# Makes all symbols private by default to avoid unintended conflict
+# with other gems. To explicitly export symbols you can use RUBY_FUNC_EXPORTED
+# selectively, or entirely remove this flag.
+append_cflags("-fvisibility=hidden")
+append_cflags("-O3")
+
+if ENV["SANITIZE"]
+  $CFLAGS << " -fsanitize=address,undefined -fno-omit-frame-pointer" # rubocop:disable Style/GlobalVars
+  $LDFLAGS << " -fsanitize=address,undefined" # rubocop:disable Style/GlobalVars
+end
+
+create_makefile("guardinari/guardinari")