odata_duty 0.30.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40bb7b15362438457b9d5c0db888c0b0d7bf59e4ce663dcc137d89bbedd4d415
+  data.tar.gz: d9fe2a78f192516121b742c6460294ad3325c13724e6ae415d713e75841d02e2
+SHA512:
+  metadata.gz: 5a417712f769ca96f93d8c5b15758011f798d07cc10e4f8900bc9ff1df8e98eb74d2c6a0a38e8ecd2d5f4bf2463e3910fe11e291d1f1b35fe1712a3988794b3e
+  data.tar.gz: 99925b2b64b8832fa00b713ccb1867a5260a070b3437362df1ca2c4f17421c3fbb2fa9d2dc1b5b603b88fcdc57461a6672f817b87249d96227db4d0619de10d1

data/README.md

@@ -0,0 +1,312 @@
+# OdataDuty
+
+**OdataDuty** is a Ruby gem that lets you define structured data and operations once using a simple DSL — and expose them seamlessly to analytics tools (like PowerBI), no-code platforms (like PowerAutomate), and AI systems (via JSON-RPC or the Model Context Protocol).
+
+It’s designed around the principle of _"define once, serve everywhere"_: you model your entities, properties, filters, and behaviors in Ruby, and OdataDuty takes care of transforming that into formats and protocols your tools and agents understand.
+
+---
+
+## ✨ Why use OdataDuty?
+
+- ✅ Define your data model and logic in plain Ruby
+- ✅ Support schema-based APIs (OpenAPI/Swagger)
+- ✅ Avoid repeating business logic in multiple layers or formats
+- ✅ Build for humans and works with reporting tools, automation tools, and LLMs (WIP) simultaneously
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'odata_duty'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it manually:
+
+```bash
+gem install odata_duty
+```
+
+### Rails Integration
+
+If you're using Rails, you can use the included generators to quickly set up OdataDuty:
+
+1. Set up the basic OData API structure:
+```bash
+bin/rails generate odata_duty:install
+```
+
+2. Generate entity types and sets:
+```bash
+bin/rails generate odata_duty:entity_set Product name:string price:decimal category:string
+```
+
+See the [Entity Set Generator documentation](doc/entity_set_generator.md) for more details.
+
+---
+
+## Getting Started
+
+> The gem assumes basic familiarity with OData concepts.  
+> If you’re new, check out the [OData Crash Course](doc/odata_crash_course.md).
+
+### 🔧 Key Features
+
+- **Entity and property definition** using a simple DSL
+- **Filtering, paging, and count support** (`$filter` supports implicit `and` and flat single-operator `or`, e.g. `color eq 'red' or color eq 'blue'`, via the `od_filter_or` hook; mixing `and`/`or` or using parentheses is not supported)
+- **Complex types and enums**
+- **Individual item retrieval and creation**
+- **Schema introspection and OpenAPI generation**
+
+---
+
+## DSL Quick Example
+
+```ruby
+require 'odata_duty'
+
+class PersonEntity < OdataDuty::EntityType
+  property_ref 'id', String
+  property 'user_name', String, nullable: false
+  property 'name', String
+  property 'emails', [String], nullable: false
+end
+
+class PeopleSet < OdataDuty::EntitySet
+  entity_type PersonEntity
+
+  def od_after_init
+    @records = Person.active
+  end
+
+  def collection
+    @records
+  end
+
+  def individual(id)
+    @records.find(id)
+  end
+
+  def create(data)
+    Person.create!(username: data.user_name, name: data.name, emails: data.emails)
+  end
+end
+
+class SampleSchema < OdataDuty::Schema
+  namespace 'SampleSpace'
+  entity_sets [PeopleSet]
+  base_url Rails.application.routes.url_helpers.api_root_url
+end
+```
+
+Implementing `create` makes a set insertable, `update` makes it updatable, and `delete` makes it deletable; omitting them keeps the set read-only. Each choice is reflected automatically across `$oas2`, `$metadata`, and MCP — see [Using `create`, `update`, and `delete`](doc/using_create_update_and_delete.md).
+
+By default the entity-set name comes from the class name: a class named `<X>EntitySet` or `<X>Set` exposes entity set `<X>` (the suffix is stripped), so `PeopleSet` above serves `People`. Pass an explicit `name`/`url` to override.
+
+---
+
+## Rails Integration Example
+
+You can quickly generate the boilerplate controller, routes and schema with:
+
+```bash
+bin/rails generate odata_duty:install
+```
+
+```ruby
+# config/routes.rb
+scope '/api' do
+  root 'api#index'
+  get '$metadata' => 'api#metadata'
+  get '$oas2' => 'api#oas2'
+  get '*url' => 'api#show'
+  post '*url' => 'api#create'
+end
+```
+
+```ruby
+# app/controllers/api_controller.rb
+
+def index
+  render json: OdataDuty::EdmxSchema.index_hash(schema)
+end
+
+def metadata
+  render xml: OdataDuty::EdmxSchema.metadata_xml(schema)
+end
+
+# `OAS2.build_json` requires a builder-DSL schema (`SchemaBuilder.build`), not a class-based `Schema`.
+def oas2
+  # CORS header so Power Automate can import `$oas2` from URL — see doc/using_oas2.md.
+  response.set_header('Access-Control-Allow-Origin', '*')
+  render json: OdataDuty::OAS2.build_json(schema)
+end
+
+def show
+  render json: schema.execute(params[:url], context: self, query_options: query_options)
+end
+
+def create
+  render json: schema.create(params[:url], context: self, query_options: query_options)
+end
+
+private
+
+def query_options
+  params.to_unsafe_hash.except('url', 'action', 'controller', 'format')
+end
+
+def schema
+  @schema ||= OdataDuty::SchemaBuilder.build(namespace: 'MySpace', host: request.host_with_port,
+                                          scheme: request.scheme, base_path: api_index_path) do |s|
+    s.title = "My Dynamic API"
+    s.version = '0.0.1'
+    person_entity = s.add_entity_type(name: 'Person') do |et|
+      et.property_ref 'id', String
+      et.property 'user_name', String, nullable: false
+    end
+    s.add_entity_set(url: 'People', entity_type: person_entity,
+                      resolver: 'PeopleResolver')
+  end
+end
+```
+
+In the builder DSL the entity-set name defaults from the resolver: `resolver: '<Namespace>::<X>Resolver'` with no `name:` yields entity set `<X>` (the namespace and the `Resolver` suffix are stripped). Above, `resolver: 'PeopleResolver'` would default to `People`; the explicit `url: 'People'` sets it directly.
+
+When a builder resolver's `collection` / `individual` raises, the error's backtrace is prefixed with the resolver's own method, its `od_after_init`, and the `add_entity_set` call site so failures point at your code first.
+
+```ruby
+# app/models/people_resolver.rb
+class PeopleResolver < OdataDuty::SetResolver
+  def od_after_init
+    @records = Person.all
+  end
+
+  def od_filter_eq(property_name, value)
+    @records = @records.where(property_name.to_sym => value)
+  end
+
+  def od_filter_ne(property_name, value)
+    @records = @records.where.not(property_name.to_sym => value)
+  end
+
+  def od_filter_gt(property_name, value)
+    @records = @records.where("#{property_name} > ?", value)
+  end
+
+  def od_filter_lt(property_name, value)
+    @records = @records.where("#{property_name} < ?", value)
+  end
+
+  # Flat single-operator `or`, e.g. `color eq 'red' or color eq 'blue'`.
+  # Called once with every or'd predicate. Mixing `and`/`or` and parentheses are not supported.
+  def od_filter_or(predicates)
+    clauses = predicates.map do |p|
+      case p.operation
+      when :eq then @records.where(p.property_name => p.value)
+      when :ne then @records.where.not(p.property_name => p.value)
+      when :gt then @records.where("#{p.property_name} > ?", p.value)
+      when :ge then @records.where("#{p.property_name} >= ?", p.value)
+      when :lt then @records.where("#{p.property_name} < ?", p.value)
+      when :le then @records.where("#{p.property_name} <= ?", p.value)
+      else
+        raise ArgumentError, "Unsupported filter operation: #{p.operation.inspect}"
+      end
+    end
+    @records = clauses.reduce(:or)
+  end
+
+  def count
+    @records.count
+  end
+
+  def collection
+    @records
+  end
+
+  def individual(id)
+    @records.find { |record| record.id == id }
+  end
+end
+```
+
+---
+
+## 📚 Further Documentation
+
+- [OData Crash Course](doc/odata_crash_course.md)
+- [MCP Crash Course](doc/mcp_crash_course.md)
+- [Using MCP](doc/using_mcp.md)
+- [Using `$select`](doc/using_select.md)
+- [Using `$search`](doc/using_search.md)
+- [Using `create`, `update`, and `delete`](doc/using_create_update_and_delete.md)
+- [Using `computed` (read-only) properties](doc/using_computed.md)
+- [Using `$oas2` (OpenAPI/Swagger) with Power Automate](doc/using_oas2.md)
+
+> **Documentation convention:** Every externally-facing feature (a new DSL option,
+> query option, or protocol surface) ships with a `doc/using_*.md` guide and a link
+> from the Further Documentation list above. Lead integration examples with the
+> Rails-controller pattern (the primary audience); show raw Rack only as a secondary,
+> runnable reference.
+
+---
+
+## TODO
+
+- Add support for composite keys
+- Add support for schema descriptions
+- Extend protocol adapters (MCP tools, resource reading)
+
+---
+
+## Development
+
+```bash
+bin/setup     # Install dependencies
+rake spec     # Run the test suite
+bin/console   # Open interactive console
+```
+
+### Test Server
+
+To run the test server with auto-restart:
+
+```bash
+bundle exec rerun -- bundle exec rackup spec/config.ru
+```
+
+For MCP debugging with the inspector:
+
+```bash
+npx @modelcontextprotocol/inspector@0.15.0 -e PORT=9292 bundle exec rackup spec/config.ru
+```
+
+To install this gem locally:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+```bash
+bundle exec rake release
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/NEXL-LTS/odata_duty-ruby](https://github.com/NEXL-LTS/odata_duty-ruby).
+
+If you're interested in extending the DSL to support new protocols or tool integrations, open an issue or start a discussion — the architecture is designed for extensibility.
+
+---

data/lib/generators/odata_duty/entity_set/entity_set_generator.rb

@@ -0,0 +1,56 @@
+require 'rails/generators'
+
+module OdataDuty
+  module Generators
+    # EntitySetGenerator creates OData entity types and sets
+    class EntitySetGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :attributes, type: :array, default: [], banner: 'field:type field:type'
+
+      class_option :skip_tests, type: :boolean, default: false, desc: 'Skip test file generation'
+
+      def create_entity_type
+        template 'entity_type.rb.erb', File.join('app/odata', "#{file_name}_entity.rb")
+      end
+
+      def create_active_record_concern
+        template 'odata_active_record_concern.rb.erb',
+                 File.join('app/odata', 'odata_active_record_concern.rb')
+      end
+
+      def create_entity_set
+        template 'entity_set.rb.erb', File.join('app/odata', "#{file_name}_set.rb")
+      end
+
+      def create_tests
+        return if options[:skip_tests]
+
+        template 'entity_type_spec.rb.erb', File.join('spec/odata', "#{file_name}_entity_spec.rb")
+        template 'entity_set_spec.rb.erb', File.join('spec/odata', "#{file_name}_set_spec.rb")
+      end
+
+      private
+
+      def attribute_type_map
+        {
+          'string' => 'String',
+          'text' => 'String',
+          'integer' => 'Integer',
+          'int' => 'Integer',
+          'datetime' => 'Time',
+          'timestamp' => 'Time',
+          'time' => 'Time',
+          'date' => 'Date',
+          'boolean' => 'TrueClass',
+          'bool' => 'TrueClass'
+        }
+      end
+
+      def odata_type(type)
+        type_key = type.to_s.downcase
+        attribute_type_map.fetch(type_key, 'String')
+      end
+    end
+  end
+end

data/lib/generators/odata_duty/entity_set/templates/entity_set.rb.erb

@@ -0,0 +1,20 @@
+class <%= class_name %>Set < OdataDuty::EntitySet
+  include OdataActiveRecordConcern
+  entity_type <%= class_name %>Entity
+
+  def od_after_init
+    @records = <%= class_name %>.active
+  end
+
+  def create(data)
+    <%= class_name %>.create!(<% attributes.each do |attr| %><%= attr.name %>: data.<%= attr.name %>,<% end %>)
+  end
+
+  def delete(id)
+    record = @records.find_by(<%= attributes.first.name %>: id)
+    return nil unless record
+
+    record.destroy!
+    record
+  end
+end

data/lib/generators/odata_duty/entity_set/templates/entity_set_spec.rb.erb

@@ -0,0 +1,38 @@
+require 'rails_helper'
+
+RSpec.describe <%= class_name %>Set do
+  let(:context) { { } }
+  let(:entity_set) { <%= class_name %>Set.new(context) }
+
+  it 'returns all records' do
+    expect(entity_set.collection).to eq(<%= class_name %>.active)
+  end
+
+  it 'finds individual record' do
+    record = <%= class_name %>.create!(<%= attributes.map { |attr| "#{attr.name}: '#{attr.name}_value'" }.join(', ') %>)
+    expect(entity_set.individual(record.id)).to eq(record)
+  end
+
+  it 'creates a new record' do
+    data = OpenStruct.new(<%= attributes.map { |attr| "#{attr.name}: '#{attr.name}_new'" }.join(', ') %>)
+    expect { entity_set.create(data) }.to change { <%= class_name %>.count }.by(1)
+  end
+
+  describe '#delete' do
+    it 'removes an existing record' do
+      record = <%= class_name %>.create!(<%= attributes.map { |attr| "#{attr.name}: '#{attr.name}_value'" }.join(', ') %>)
+      expect { entity_set.delete(record.<%= attributes.first.name %>) }.to change { <%= class_name %>.count }.by(-1)
+    end
+
+    it 'returns a falsey value and does not change the count when not found' do
+      expect(entity_set.delete('non_existent_id')).to be_falsey
+      expect { entity_set.delete('non_existent_id') }.not_to change { <%= class_name %>.count }
+    end
+  end
+
+  describe 'entity_type' do
+    it 'uses the correct entity type' do
+      expect(described_class.entity_type).to eq(<%= class_name %>Entity)
+    end
+  end
+end

data/lib/generators/odata_duty/entity_set/templates/entity_type.rb.erb

@@ -0,0 +1,6 @@
+class <%= class_name %>Entity < OdataDuty::EntityType
+  property_ref '<%= attributes.first.name %>', <%= odata_type(attributes.first.type) %>, nullable: false
+<% attributes.slice(1..-1).each do |attr| -%>
+  property '<%= attr.name %>', <%= odata_type(attr.type) %>
+<% end -%>
+end

data/lib/generators/odata_duty/entity_set/templates/entity_type_spec.rb.erb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+RSpec.describe <%= class_name %>Entity do
+  let(:attributes) do
+    {
+      <% attributes.slice(1..-1).each do |attr| %>
+        <%= attr.name %>: '',
+      <% end %>
+    }
+  end
+  let(:record) { <%= class_name %>.create!(attributes) }
+  let(:context) { {} }
+  subject(:entity) { described_class.new(record, context) }
+
+  <% attributes.each do |attr| %>
+    describe '<%= attr.name %> property' do
+      it { expect(entity.<%= attr.name %>).to eq(record.<%= attr.name %>) }
+    end
+  <% end %>
+end

data/lib/generators/odata_duty/entity_set/templates/odata_active_record_concern.rb.erb

@@ -0,0 +1,109 @@
+module OdataActiveRecordConcern
+  def max_results
+    1000
+  end
+
+  def od_top(value)
+    if value.to_i > max_results
+      raise OdataDuty::ClientError, "Invalid $top cannot be more than \#{max_results}"
+    end
+
+    @records = @records.limit(value)
+  end
+
+  def od_skip(value)
+    @records = @records.offset(value)
+  end
+
+  def od_skiptoken(value)
+    @skiptoken = value
+    @records = @records.reorder(:id).where("\#{@records.table_name}.id > ?", value)
+  end
+
+  def count
+    @records.count
+  end
+
+  def collection
+    if @records.count > max_results
+      @records.safe_loading.reorder(:id).limit(max_results).to_a.tap do |r|
+        od_next_link_skiptoken(r.last.id)
+      end
+    else
+      @records.safe_loading
+    end
+  end
+
+  def individual(id)
+    @records.find_by(id: id)
+  end
+  # ODATA operators:
+  # eq, ne, gt, lt, ge, and le comes from OData naming conventions
+
+  # eq: Test whether a field is equal to a constant value
+  def od_filter_eq(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.where(property_name.to_sym => value)
+  end
+
+  # ne: Test whether a field is not equal to a constant value
+  def od_filter_ne(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.where.not(property_name.to_sym => value)
+  end
+
+  # gt: Test whether a field is greater than a constant value
+  def od_filter_gt(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.order(property_name => :asc)
+                        .where("\#{@records.table_name}.\#{property_name} > ?", value)
+  end
+
+  # ge: Test whether a field is greater than or equal to a constant value
+  def od_filter_ge(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.order(property_name => :asc)
+                        .where(property_name.to_sym => value..)
+  end
+
+  # lt: Test whether a field is less than a constant value
+  def od_filter_lt(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.order(property_name => :desc)
+                        .where(property_name.to_sym => ...value)
+  end
+
+  # le: Test whether a field is less than or equal to a constant value
+  def od_filter_le(property_name, value)
+    assert_filterable_property(property_name)
+    @records = @records.order(property_name => :desc)
+                        .where(property_name.to_sym => ..value)
+  end
+
+  # or: Union of records satisfying any of the or'd predicates
+  def od_filter_or(predicates)
+    clauses = predicates.map do |p|
+      assert_filterable_property(p.property_name)
+      case p.operation
+      when :eq then @records.where(p.property_name => p.value)
+      when :ne then @records.where.not(p.property_name => p.value)
+      when :gt then @records.where("\#{@records.table_name}.\#{p.property_name} > ?", p.value)
+      when :ge then @records.where("\#{@records.table_name}.\#{p.property_name} >= ?", p.value)
+      when :lt then @records.where("\#{@records.table_name}.\#{p.property_name} < ?", p.value)
+      when :le then @records.where("\#{@records.table_name}.\#{p.property_name} <= ?", p.value)
+      else
+        raise ArgumentError, "Unsupported filter operation: \#{p.operation.inspect}"
+      end
+    end
+    @records = clauses.reduce(:or)
+  end
+
+  protected
+
+  def assert_filterable_property(property_name)
+    return if @records.column_names.include?(property_name.to_s)
+    return if @records.attribute_aliases.keys.include?(property_name.to_s)
+
+    raise NotImplementedError, "Filtering on \#{property_name} not supported"
+  end
+end

data/lib/generators/odata_duty/entity_set/templates/resolver.rb.erb

@@ -0,0 +1,39 @@
+class <%= class_name %>Resolver < OdataDuty::SetResolver
+  def od_after_init
+    # Initialize any resources needed for this entity set
+    @<%= file_name.pluralize %> = []
+  end
+  
+  def collection
+    # Return all instances of this entity
+    @<%= file_name.pluralize %>
+  end
+  
+  def individual(id)
+    # Find and return a specific entity by id
+    @<%= file_name.pluralize %>.find { |item| item.<%= attributes.first.name %> == id }
+  end
+  
+  # Optional: Implement create method to support POST operations
+  def create(data)
+    # Create a new entity from the submitted data
+    new_<%= file_name %> = OpenStruct.new(
+<% attributes.each do |attr| %>
+      <%= attr.name %>: data['<%= attr.name %>'],
+<% end %>
+    )
+    
+    @<%= file_name.pluralize %> << new_<%= file_name %>
+    new_<%= file_name %>
+  end
+
+  # Optional: Implement delete method to support DELETE operations
+  def delete(id)
+    # Find and remove the entity by id; return truthy on success, falsey if not found
+    <%= file_name %> = @<%= file_name.pluralize %>.find { |item| item.<%= attributes.first.name %> == id }
+    return nil unless <%= file_name %>
+
+    @<%= file_name.pluralize %>.delete(<%= file_name %>)
+    <%= file_name %>
+  end
+end

data/lib/generators/odata_duty/entity_set/templates/resolver_spec.rb.erb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+RSpec.describe <%= class_name %>Resolver do
+  let(:context) { instance_double(OdataDuty::Context) }
+  
+  subject { described_class.new(context: context, init_args: nil) }
+  
+  before do
+    allow(subject).to receive(:collection).and_return([])
+  end
+  
+  describe '#collection' do
+    it 'returns a collection of entities' do
+      expect(subject.collection).to be_an(Array)
+    end
+  end
+  
+  describe '#individual' do
+    let(:test_entity) { OpenStruct.new(<%= attributes.first.name %>: 'test_id') }
+    
+    before do
+      allow(subject).to receive(:collection).and_return([test_entity])
+    end
+    
+    it 'returns a specific entity by id' do
+      expect(subject.individual('test_id')).to eq(test_entity)
+    end
+    
+    it 'returns nil when the entity is not found' do
+      expect(subject.individual('non_existent_id')).to be_nil
+    end
+  end
+
+  describe '#delete' do
+    let(:test_entity) { OpenStruct.new(<%= attributes.first.name %>: 'test_id') }
+
+    before do
+      subject.instance_variable_set(:@<%= file_name.pluralize %>, [test_entity])
+    end
+
+    it 'removes an existing entity by id' do
+      expect(subject.delete('test_id')).to eq(test_entity)
+      expect(subject.instance_variable_get(:@<%= file_name.pluralize %>)).not_to include(test_entity)
+    end
+
+    it 'returns a falsey value when the entity is not found' do
+      expect(subject.delete('non_existent_id')).to be_falsey
+    end
+  end
+end