services/api/app/controllers/arvados/v1/schema_controller.rb

   1 # Copyright (C) The Arvados Authors. All rights reserved.
   2 #
   3 # SPDX-License-Identifier: AGPL-3.0
   4
   5 class Arvados::V1::SchemaController < ApplicationController
   6   skip_before_action :catch_redirect_hint
   7   skip_before_action :find_objects_for_index
   8   skip_before_action :find_object_by_uuid
   9   skip_before_action :load_filters_param
  10   skip_before_action :load_limit_offset_order_params
  11   skip_before_action :load_select_param
  12   skip_before_action :load_read_auths
  13   skip_before_action :load_where_param
  14   skip_before_action :render_404_if_no_object
  15   skip_before_action :require_auth_scope
  16
  17   include DbCurrentTime
  18
  19   def index
  20     expires_in 24.hours, public: true
  21     send_json discovery_doc
  22   end
  23
  24   protected
  25
  26   ActionNameMap = {
  27     'destroy' => 'delete',
  28     'index' => 'list',
  29     'show' => 'get',
  30   }
  31
  32   def discovery_doc
  33     Rails.application.eager_load!
  34     remoteHosts = {}
  35     Rails.configuration.RemoteClusters.each {|k,v| if k != :"*" then remoteHosts[k] = v["Host"] end }
  36     discovery = {
  37       kind: "discovery#restDescription",
  38       discoveryVersion: "v1",
  39       id: "arvados:v1",
  40       name: "arvados",
  41       version: "v1",
  42       # format is YYYYMMDD, must be fixed width (needs to be lexically
  43       # sortable), updated manually, may be used by clients to
  44       # determine availability of API server features.
  45       revision: "20240502",
  46       source_version: AppVersion.hash,
  47       sourceVersion: AppVersion.hash, # source_version should be deprecated in the future
  48       packageVersion: AppVersion.package_version,
  49       generatedAt: db_current_time.iso8601,
  50       title: "Arvados API",
  51       description: "The API to interact with Arvados.",
  52       documentationLink: "http://doc.arvados.org/api/index.html",
  53       defaultCollectionReplication: Rails.configuration.Collections.DefaultReplication,
  54       protocol: "rest",
  55       baseUrl: root_url + "arvados/v1/",
  56       basePath: "/arvados/v1/",
  57       rootUrl: root_url,
  58       servicePath: "arvados/v1/",
  59       batchPath: "batch",
  60       uuidPrefix: Rails.configuration.ClusterID,
  61       defaultTrashLifetime: Rails.configuration.Collections.DefaultTrashLifetime,
  62       blobSignatureTtl: Rails.configuration.Collections.BlobSigningTTL,
  63       maxRequestSize: Rails.configuration.API.MaxRequestSize,
  64       maxItemsPerResponse: Rails.configuration.API.MaxItemsPerResponse,
  65       dockerImageFormats: Rails.configuration.Containers.SupportedDockerImageFormats.keys,
  66       crunchLogUpdatePeriod: Rails.configuration.Containers.Logging.LogUpdatePeriod,
  67       crunchLogUpdateSize: Rails.configuration.Containers.Logging.LogUpdateSize,
  68       remoteHosts: remoteHosts,
  69       remoteHostsViaDNS: Rails.configuration.RemoteClusters["*"].Proxy,
  70       websocketUrl: Rails.configuration.Services.Websocket.ExternalURL.to_s,
  71       workbenchUrl: Rails.configuration.Services.Workbench1.ExternalURL.to_s,
  72       workbench2Url: Rails.configuration.Services.Workbench2.ExternalURL.to_s,
  73       keepWebServiceUrl: Rails.configuration.Services.WebDAV.ExternalURL.to_s,
  74       parameters: {
  75         alt: {
  76           type: "string",
  77           description: "Data format for the response.",
  78           default: "json",
  79           enum: [
  80             "json"
  81           ],
  82           enumDescriptions: [
  83             "Responses with Content-Type of application/json"
  84           ],
  85           location: "query"
  86         },
  87         fields: {
  88           type: "string",
  89           description: "Selector specifying which fields to include in a partial response.",
  90           location: "query"
  91         },
  92         key: {
  93           type: "string",
  94           description: "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
  95           location: "query"
  96         },
  97         oauth_token: {
  98           type: "string",
  99           description: "OAuth 2.0 token for the current user.",
 100           location: "query"
 101         }
 102       },
 103       auth: {
 104         oauth2: {
 105           scopes: {
 106             "https://api.arvados.org/auth/arvados" => {
 107               description: "View and manage objects"
 108             },
 109             "https://api.arvados.org/auth/arvados.readonly" => {
 110               description: "View objects"
 111             }
 112           }
 113         }
 114       },
 115       schemas: {},
 116       resources: {}
 117     }
 118
 119     ActiveRecord::Base.descendants.reject(&:abstract_class?).sort_by(&:to_s).each do |k|
 120       begin
 121         ctl_class = "Arvados::V1::#{k.to_s.pluralize}Controller".constantize
 122       rescue
 123         # No controller -> no discovery.
 124         next
 125       end
 126       object_properties = {}
 127       k.columns.
 128         select { |col| k.selectable_attributes.include? col.name }.
 129         collect do |col|
 130         if k.serialized_attributes.has_key? col.name
 131           object_properties[col.name] = {
 132             type: k.serialized_attributes[col.name].object_class.to_s
 133           }
 134         elsif k.attribute_types[col.name].is_a? JsonbType::Hash
 135           object_properties[col.name] = {
 136             type: Hash.to_s
 137           }
 138         elsif k.attribute_types[col.name].is_a? JsonbType::Array
 139           object_properties[col.name] = {
 140             type: Array.to_s
 141           }
 142         else
 143           object_properties[col.name] = {
 144             type: col.type
 145           }
 146         end
 147       end
 148       discovery[:schemas][k.to_s + 'List'] = {
 149         id: k.to_s + 'List',
 150         description: k.to_s + ' list',
 151         type: "object",
 152         properties: {
 153           kind: {
 154             type: "string",
 155             description: "Object type. Always arvados##{k.to_s.camelcase(:lower)}List.",
 156             default: "arvados##{k.to_s.camelcase(:lower)}List"
 157           },
 158           etag: {
 159             type: "string",
 160             description: "List version."
 161           },
 162           items: {
 163             type: "array",
 164             description: "The list of #{k.to_s.pluralize}.",
 165             items: {
 166               "$ref" => k.to_s
 167             }
 168           },
 169           next_link: {
 170             type: "string",
 171             description: "A link to the next page of #{k.to_s.pluralize}."
 172           },
 173           next_page_token: {
 174             type: "string",
 175             description: "The page token for the next page of #{k.to_s.pluralize}."
 176           },
 177           selfLink: {
 178             type: "string",
 179             description: "A link back to this list."
 180           }
 181         }
 182       }
 183       discovery[:schemas][k.to_s] = {
 184         id: k.to_s,
 185         description: k.to_s,
 186         type: "object",
 187         uuidPrefix: (k.respond_to?(:uuid_prefix) ? k.uuid_prefix : nil),
 188         properties: {
 189           uuid: {
 190             type: "string",
 191             description: "Object ID."
 192           },
 193           etag: {
 194             type: "string",
 195             description: "Object version."
 196           }
 197         }.merge(object_properties)
 198       }
 199       discovery[:resources][k.to_s.underscore.pluralize] = {
 200         methods: {
 201           get: {
 202             id: "arvados.#{k.to_s.underscore.pluralize}.get",
 203             path: "#{k.to_s.underscore.pluralize}/{uuid}",
 204             httpMethod: "GET",
 205             description: "Gets a #{k.to_s}'s metadata by UUID.",
 206             parameters: {
 207               uuid: {
 208                 type: "string",
 209                 description: "The UUID of the #{k.to_s} in question.",
 210                 required: true,
 211                 location: "path"
 212               }
 213             },
 214             parameterOrder: [
 215               "uuid"
 216             ],
 217             response: {
 218               "$ref" => k.to_s
 219             },
 220             scopes: [
 221               "https://api.arvados.org/auth/arvados",
 222               "https://api.arvados.org/auth/arvados.readonly"
 223             ]
 224           },
 225           list: {
 226             id: "arvados.#{k.to_s.underscore.pluralize}.list",
 227             path: k.to_s.underscore.pluralize,
 228             httpMethod: "GET",
 229             description:
 230               %|List #{k.to_s.pluralize}.
 231
 232                    The <code>list</code> method returns a
 233                    <a href="/api/resources.html">resource list</a> of
 234                    matching #{k.to_s.pluralize}. For example:
 235
 236                    <pre>
 237                    {
 238                     "kind":"arvados##{k.to_s.camelcase(:lower)}List",
 239                     "etag":"",
 240                     "self_link":"",
 241                     "next_page_token":"",
 242                     "next_link":"",
 243                     "items":[
 244                        ...
 245                     ],
 246                     "items_available":745,
 247                     "_profile":{
 248                      "request_time":0.157236317
 249                     }
 250                     </pre>|,
 251             parameters: {
 252             },
 253             response: {
 254               "$ref" => "#{k.to_s}List"
 255             },
 256             scopes: [
 257               "https://api.arvados.org/auth/arvados",
 258               "https://api.arvados.org/auth/arvados.readonly"
 259             ]
 260           },
 261           create: {
 262             id: "arvados.#{k.to_s.underscore.pluralize}.create",
 263             path: "#{k.to_s.underscore.pluralize}",
 264             httpMethod: "POST",
 265             description: "Create a new #{k.to_s}.",
 266             parameters: {},
 267             request: {
 268               required: true,
 269               properties: {
 270                 k.to_s.underscore => {
 271                   "$ref" => k.to_s
 272                 }
 273               }
 274             },
 275             response: {
 276               "$ref" => k.to_s
 277             },
 278             scopes: [
 279               "https://api.arvados.org/auth/arvados"
 280             ]
 281           },
 282           update: {
 283             id: "arvados.#{k.to_s.underscore.pluralize}.update",
 284             path: "#{k.to_s.underscore.pluralize}/{uuid}",
 285             httpMethod: "PUT",
 286             description: "Update attributes of an existing #{k.to_s}.",
 287             parameters: {
 288               uuid: {
 289                 type: "string",
 290                 description: "The UUID of the #{k.to_s} in question.",
 291                 required: true,
 292                 location: "path"
 293               }
 294             },
 295             request: {
 296               required: true,
 297               properties: {
 298                 k.to_s.underscore => {
 299                   "$ref" => k.to_s
 300                 }
 301               }
 302             },
 303             response: {
 304               "$ref" => k.to_s
 305             },
 306             scopes: [
 307               "https://api.arvados.org/auth/arvados"
 308             ]
 309           },
 310           delete: {
 311             id: "arvados.#{k.to_s.underscore.pluralize}.delete",
 312             path: "#{k.to_s.underscore.pluralize}/{uuid}",
 313             httpMethod: "DELETE",
 314             description: "Delete an existing #{k.to_s}.",
 315             parameters: {
 316               uuid: {
 317                 type: "string",
 318                 description: "The UUID of the #{k.to_s} in question.",
 319                 required: true,
 320                 location: "path"
 321               }
 322             },
 323             response: {
 324               "$ref" => k.to_s
 325             },
 326             scopes: [
 327               "https://api.arvados.org/auth/arvados"
 328             ]
 329           }
 330         }
 331       }
 332       # Check for Rails routes that don't match the usual actions
 333       # listed above
 334       d_methods = discovery[:resources][k.to_s.underscore.pluralize][:methods]
 335       Rails.application.routes.routes.each do |route|
 336         action = route.defaults[:action]
 337         httpMethod = ['GET', 'POST', 'PUT', 'DELETE'].map { |method|
 338           method if route.verb.match(method)
 339         }.compact.first
 340         if httpMethod &&
 341           route.defaults[:controller] == 'arvados/v1/' + k.to_s.underscore.pluralize &&
 342           ctl_class.action_methods.include?(action)
 343           method_name = ActionNameMap[action] || action
 344           method_key = method_name.to_sym
 345           if !d_methods[method_key]
 346             method = {
 347               id: "arvados.#{k.to_s.underscore.pluralize}.#{method_name}",
 348               path: route.path.spec.to_s.sub('/arvados/v1/','').sub('(.:format)','').sub(/:(uu)?id/,'{uuid}'),
 349               httpMethod: httpMethod,
 350               description: "#{method_name} #{k.to_s.underscore.pluralize}",
 351               parameters: {},
 352               response: {
 353                 "$ref" => (method_name == 'list' ? "#{k.to_s}List" : k.to_s)
 354               },
 355               scopes: [
 356                 "https://api.arvados.org/auth/arvados"
 357               ]
 358             }
 359             route.segment_keys.each do |key|
 360               if key != :format
 361                 key = :uuid if key == :id
 362                 method[:parameters][key] = {
 363                   type: "string",
 364                   description: "",
 365                   required: true,
 366                   location: "path"
 367                 }
 368               end
 369             end
 370           else
 371             # We already built a generic method description, but we
 372             # might find some more required parameters through
 373             # introspection.
 374             method = d_methods[method_key]
 375           end
 376           if ctl_class.respond_to? "_#{action}_requires_parameters".to_sym
 377             ctl_class.send("_#{action}_requires_parameters".to_sym).each do |l, v|
 378               if v.is_a? Hash
 379                 method[:parameters][l] = v
 380               else
 381                 method[:parameters][l] = {}
 382               end
 383               if !method[:parameters][l][:default].nil?
 384                 # The JAVA SDK is sensitive to all values being strings
 385                 method[:parameters][l][:default] = method[:parameters][l][:default].to_s
 386               end
 387               method[:parameters][l][:type] ||= 'string'
 388               method[:parameters][l][:description] ||= ''
 389               method[:parameters][l][:location] = (route.segment_keys.include?(l) ? 'path' : 'query')
 390               if method[:parameters][l][:required].nil?
 391                 method[:parameters][l][:required] = v != false
 392               end
 393             end
 394           end
 395           d_methods[method_key] = method
 396         end
 397       end
 398     end
 399
 400     # The computed_permissions controller does not offer all of the
 401     # usual methods and attributes.  Modify discovery doc accordingly.
 402     discovery[:resources]['computed_permissions'][:methods].select! do |method|
 403       method == :list
 404     end
 405     discovery[:resources]['computed_permissions'][:methods][:list][:parameters].select! do |param|
 406       ![:cluster_id, :bypass_federation, :offset].include?(param)
 407     end
 408     discovery[:schemas]['ComputedPermission'].delete(:uuidPrefix)
 409     discovery[:schemas]['ComputedPermission'][:properties].select! do |prop|
 410       ![:uuid, :etag].include?(prop)
 411     end
 412
 413     # The 'replace_files' option is implemented in lib/controller,
 414     # not Rails -- we just need to add it here so discovery-aware
 415     # clients know how to validate it.
 416     [:create, :update].each do |action|
 417       discovery[:resources]['collections'][:methods][action][:parameters]['replace_files'] = {
 418         type: 'object',
 419         description: 'Files and directories to initialize/replace with content from other collections.',
 420         required: false,
 421         location: 'query',
 422         properties: {},
 423         additionalProperties: {type: 'string'},
 424       }
 425     end
 426
 427     discovery[:resources]['configs'] = {
 428       methods: {
 429         get: {
 430           id: "arvados.configs.get",
 431           path: "config",
 432           httpMethod: "GET",
 433           description: "Get public config",
 434           parameters: {
 435           },
 436           parameterOrder: [
 437           ],
 438           response: {
 439           },
 440           scopes: [
 441             "https://api.arvados.org/auth/arvados",
 442             "https://api.arvados.org/auth/arvados.readonly"
 443           ]
 444         },
 445       }
 446     }
 447
 448     discovery[:resources]['vocabularies'] = {
 449       methods: {
 450         get: {
 451           id: "arvados.vocabularies.get",
 452           path: "vocabulary",
 453           httpMethod: "GET",
 454           description: "Get vocabulary definition",
 455           parameters: {
 456           },
 457           parameterOrder: [
 458           ],
 459           response: {
 460           },
 461           scopes: [
 462             "https://api.arvados.org/auth/arvados",
 463             "https://api.arvados.org/auth/arvados.readonly"
 464           ]
 465         },
 466       }
 467     }
 468
 469     discovery[:resources]['sys'] = {
 470       methods: {
 471         get: {
 472           id: "arvados.sys.trash_sweep",
 473           path: "sys/trash_sweep",
 474           httpMethod: "POST",
 475           description: "apply scheduled trash and delete operations",
 476           parameters: {
 477           },
 478           parameterOrder: [
 479           ],
 480           response: {
 481           },
 482           scopes: [
 483             "https://api.arvados.org/auth/arvados",
 484             "https://api.arvados.org/auth/arvados.readonly"
 485           ]
 486         },
 487       }
 488     }
 489
 490     Rails.configuration.API.DisabledAPIs.each do |method, _|
 491       ctrl, action = method.to_s.split('.', 2)
 492       next if ctrl.in?(['job_tasks', 'jobs', 'keep_disks', 'nodes', 'pipeline_instances', 'pipeline_templates', 'repositories'])
 493       discovery[:resources][ctrl][:methods].delete(action.to_sym)
 494     end
 495     discovery
 496   end
 497 end