Data

Tools

Indexes

Applications

Experiments

Ruby

A summary of data about the Ruby ecosystem.

https://github.com/rails/globalid

Identify app models with a URI
https://github.com/rails/globalid

Keywords from Contributors

activerecord activejob mvc rubygems rack crash-reporting rspec rubocop background-jobs ruby-gem

Last synced: about 11 hours ago
JSON representation

Repository metadata

Identify app models with a URI

README.md

Global ID - Reference models by URI

A Global ID is an app wide URI that uniquely identifies a model instance:

gid://YourApp/Some::Model/id

This is helpful when you need a single identifier to reference different
classes of objects.

One example is job scheduling. We need to reference a model object rather than
serialize the object itself. We can pass a Global ID that can be used to locate
the model when it's time to perform the job. The job scheduler doesn't need to know
the details of model naming and IDs, just that it has a global identifier that
references a model.

Another example is a drop-down list of options, consisting of both Users and Groups.
Normally we'd need to come up with our own ad hoc scheme to reference them. With Global
IDs, we have a universal identifier that works for objects of both classes.

Usage

Mix GlobalID::Identification into any model with a .find(id) class method that returns
an instance of the model, and a .where(id:) class method that returns an enumerable of
instance(s). Support is automatically included in Active Record.

person_gid = Person.find(1).to_global_id
# => #<GlobalID ...

person_gid.uri
# => #<URI ...

person_gid.to_s
# => "gid://app/Person/1"

GlobalID::Locator.locate person_gid
# => #<Person:0x007fae94bf6298 @id="1">

locate returns nil for a blank or unparseable Global ID, and lets the
backend's own exceptions bubble up when a record can't be found. Use fetch
when you want to tell apart a record that's gone for good from a transient
backend failure:

GlobalID::Locator.fetch person_gid
# => #<Person:0x007fae94bf6298 @id="1">           # found
# => raises GlobalID::Locator::RecordNotFound     # the record no longer exists
# => raises GlobalID::Locator::RecordUnavailable  # the backend failed; retry may succeed

Both errors extend GlobalID::Locator::Error, so you can rescue either at
once. This is useful, for example, to discard a background job whose argument
points at a deleted record, without also discarding jobs that hit a temporary
database error.

Signed Global IDs

For added security GlobalIDs can also be signed to ensure that the data hasn't been tampered with.

person_sgid = Person.find(1).to_signed_global_id
# => #<SignedGlobalID:0x007fea1944b410>

person_sgid = Person.find(1).to_sgid
# => #<SignedGlobalID:0x007fea1944b410>

person_sgid.to_s
# => "BAhJIh5naWQ6Ly9pZGluYWlkaS9Vc2VyLzM5NTk5BjoGRVQ=--81d7358dd5ee2ca33189bb404592df5e8d11420e"

GlobalID::Locator.locate_signed person_sgid
# => #<Person:0x007fae94bf6298 @id="1">

Expiration

Signed Global IDs can expire sometime in the future. This is useful if there's a resource
people shouldn't have indefinite access to, like a share link.

expiring_sgid = Document.find(5).to_sgid(expires_in: 2.hours, for: 'sharing')
# => #<SignedGlobalID:0x008fde45df8937 ...>

# Within 2 hours...
GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')
# => #<Document:0x007fae94bf6298 @id="5">

# More than 2 hours later...
GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')
# => nil

In Rails, an auto-expiry of 1 month is set by default. You can alter that
default in an initializer with:

# config/initializers/global_id.rb
Rails.application.config.global_id.expires_in = 3.months

You can assign a default SGID lifetime like so:

SignedGlobalID.expires_in = 1.month

This way, any generated SGID will use that relative expiry.

It's worth noting that expiring SGIDs are not idempotent because they encode the current timestamp; repeated calls to to_sgid will produce different results. For example, in Rails

Document.find(5).to_sgid.to_s == Document.find(5).to_sgid.to_s
# => false

You need to explicitly pass expires_in: nil to generate a permanent SGID that will not expire,

# Passing a false value to either expiry option turns off expiration entirely.
never_expiring_sgid = Document.find(5).to_sgid(expires_in: nil)
# => #<SignedGlobalID:0x008fde45df8937 ...>

# Any time later...
GlobalID::Locator.locate_signed never_expiring_sgid
# => #<Document:0x007fae94bf6298 @id="5">

It's also possible to pass a specific expiry time

explicit_expiring_sgid = SecretAgentMessage.find(5).to_sgid(expires_at: Time.now.advance(hours: 1))
# => #<SignedGlobalID:0x008fde45df8937 ...>

# 1 hour later...
GlobalID::Locator.locate_signed explicit_expiring_sgid.to_s
# => nil

Note that an explicit :expires_at takes precedence over a relative :expires_in.

Purpose

You can even bump the security up some more by explaining what purpose a Signed Global ID is for.
In this way evildoers can't reuse a sign-up form's SGID on the login page. For example.

signup_person_sgid = Person.find(1).to_sgid(for: 'signup_form')
# => #<SignedGlobalID:0x007fea1984b520

GlobalID::Locator.locate_signed(signup_person_sgid.to_s, for: 'signup_form')
# => #<Person:0x007fae94bf6298 @id="1">

Locating many Global IDs

When needing to locate many Global IDs use GlobalID::Locator.locate_many or GlobalID::Locator.locate_many_signed for Signed Global IDs to allow loading
Global IDs more efficiently.

For instance, the default locator passes every model_id per model_name thus
using model_name.where(id: model_ids) versus GlobalID::Locator.locate's model_name.find(id).

In the case of looking up Global IDs from a database, it's only necessary to query
once per model_name as shown here:

gids = users.concat(people).sort_by(&:id).map(&:to_global_id)
# => [#<GlobalID:0x00007ffd6a8411a0 @uri=#<URI::GID gid://app/User/1>>,
#<GlobalID:0x00007ffd675d32b8 @uri=#<URI::GID gid://app/Student/1>>,
#<GlobalID:0x00007ffd6a840b10 @uri=#<URI::GID gid://app/User/2>>,
#<GlobalID:0x00007ffd675d2c28 @uri=#<URI::GID gid://app/Student/2>>,
#<GlobalID:0x00007ffd6a840480 @uri=#<URI::GID gid://app/User/3>>,
#<GlobalID:0x00007ffd675d2598 @uri=#<URI::GID gid://app/Student/3>>]

GlobalID::Locator.locate_many gids
# SELECT "users".* FROM "users" WHERE "users"."id" IN ($1, $2, $3)  [["id", 1], ["id", 2], ["id", 3]]
# SELECT "students".* FROM "students" WHERE "students"."id" IN ($1, $2, $3)  [["id", 1], ["id", 2], ["id", 3]]
# => [#<User id: 1>, #<Student id: 1>, #<User id: 2>, #<Student id: 2>, #<User id: 3>, #<Student id: 3>]

Note the order is maintained in the returned results.

Options

Either GlobalID::Locator.locate or GlobalID::Locator.locate_many supports a hash of options as second parameter. The supported options are:

  • :includes - A Symbol, Array, Hash or combination of them.
    The same structure you would pass into an includes method of Active Record.
    See Active Record eager loading associations.
    If present, locate or locate_many will eager load all the relationships specified here.
    Note: It only works if all the GIDs Models have those relationships.
  • :only - A class, module, or Array of classes and/or modules that are
    allowed to be located. Passing one or more classes limits instances of returned
    classes to those classes or their subclasses. Passing one or more modules in limits
    instances of returned classes to those including that module. If no classes or
    modules match, nil is returned.
  • :ignore_missing (Only for locate_many) - By default, locate_many will call #find on the model to locate the
    ids extracted from the GIDs. In Active Record (and other data stores following the same pattern),
    #find will raise an exception if a named ID can't be found. When you set this option to true,
    we will use #where(id: ids) instead, which does not raise on missing records.

Custom App Locator

A custom locator can be set for an app by calling GlobalID::Locator.use and providing an app locator to use for that app.
A custom app locator is useful when different apps collaborate and reference each others' Global IDs.
When finding a Global ID's model, the locator to use is based on the app name provided in the Global ID url.

A custom locator can either be a block or a class.

Using a block:

GlobalID::Locator.use :foo do |gid, options|
  FooRemote.const_get(gid.model_name).find(gid.model_id)
end

Using a class:

class BarLocator
  def locate(gid, options = {})
    @search_client.search name: gid.model_name, id: gid.model_id
  end
end

GlobalID::Locator.use :bar, BarLocator.new

It's recommended to inherit from GlobalID::Locator::BaseLocator (or GlobalID::Locator::UnscopedLocator for Active Record models) to get default implementations of model_class and locate_many:

class BarLocator < GlobalID::Locator::BaseLocator
  def locate(gid, options = {})
    @search_client.search name: gid.model_name, id: gid.model_id
  end
end

GlobalID::Locator.use :bar, BarLocator.new

After defining locators as above, URIs like gid://foo/Person/1 and gid://bar/Person/1 will now use the foo block locator and BarLocator respectively.
Other apps will still keep using the default locator.

Custom Model Class Derivation

By default, GlobalID derives the model class by calling constantize on the model name from the GID. Custom locators can override this behavior by implementing a model_class method. This is useful when the model name in the GID doesn't match the actual class name, or when you want to redirect to a different model.

Inherit from BaseLocator and override model_class:

class RemoteLocator < GlobalID::Locator::BaseLocator
  def model_class(gid)
    # Map remote model names to local models
    case gid.model_name
    when 'User'
      RemoteUser
    when 'Profile'
      RemoteProfile
    else
      super # Fall back to default constantize behavior
    end
  end

  def locate(gid, options = {})
    # Use the mapped model class to find the record
    model_class(gid).find_by(remote_id: gid.model_id)
  end
end

GlobalID::Locator.use :remote, RemoteLocator.new

This allows you to work with Global IDs that reference models that don't exist in your application, redirecting them to the appropriate local models.

Note: For backward compatibility, if a custom locator doesn't implement model_class, GlobalID will fall back to the default behavior (constantize) but will emit a deprecation warning. To avoid this, inherit from GlobalID::Locator::BaseLocator or GlobalID::Locator::UnscopedLocator.

Custom Default Locator

A custom default locator can be set for an app by calling GlobalID::Locator.default_locator= and providing a default locator to use for that app.

class MyCustomLocator < UnscopedLocator
  def locate(gid, options = {})
    ActiveRecord::Base.connected_to(role: :reading) do
      super(gid, options)
    end
  end

  def locate_many(gids, options = {})
    ActiveRecord::Base.connected_to(role: :reading) do
      super(gids, options)
    end
  end
end

GlobalID::Locator.default_locator = MyCustomLocator.new

Contributing to GlobalID

GlobalID is work of many contributors. You're encouraged to submit pull requests, propose
features and discuss issues.

See CONTRIBUTING.

License

GlobalID is released under the MIT License.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: about 23 hours ago

Total Commits: 288
Total Committers: 78
Avg Commits per committer: 3.692
Development Distribution Score (DDS): 0.785

Commits in past year: 24
Committers in past year: 13
Avg Commits per committer in past year: 1.846
Development Distribution Score (DDS) in past year: 0.708

Name Email Commits
Kasper Timm Hansen k****h@g****m 62
Rafael Mendonça França r****l@r****g 42
David Heinemeier Hansson d****d@l****m 19
Jeremy Kemper j****r@g****m 13
yuuji.yaginuma y****a@g****m 12
Abdelkader Boudih t****e@g****m 11
dependabot[bot] 4****] 11
Nick Veys n****k@c****m 8
Tony Han h****2@g****m 7
Dan Olson o****n@y****m 5
Jean Boussier b****t@r****g 5
Rafael Mendonça França r****a@p****r 4
Vipul A M v****d@g****m 4
Vít Ondruch v****h@r****m 3
Jun Aruga j****a@r****m 3
Akira Matsuda r****e@d****p 3
Thomas Drake-Brockman t****m@s****m 2
Petrik p****k@d****t 2
Olle Jonsson o****n@g****m 2
Aaron Patterson t****e@r****g 2
Alex Watt a****x@a****m 2
Bradley Buda b****a@g****m 2
Earlopain 1****n 2
Elia Schito e****a@s****e 2
Eugene Kenny e****y@g****m 2
George Claghorn g****e@b****m 2
Jamie Lawrence j****e@i****m 2
Jose Rafael Coello Alba r****o@f****m 2
Larry Lv l****0@g****m 2
Nikita Vasilevsky n****y@s****m 2
and 48 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 3 days ago

Total issues: 44
Total pull requests: 119
Average time to close issues: 6 months
Average time to close pull requests: 2 months
Total issue authors: 43
Total pull request authors: 66
Average comments per issue: 3.61
Average comments per pull request: 1.71
Merged pull request: 79
Bot issues: 0
Bot pull requests: 14

Past year issues: 2
Past year pull requests: 11
Past year average time to close issues: 5 months
Past year average time to close pull requests: 2 months
Past year issue authors: 2
Past year pull request authors: 9
Past year average comments per issue: 3.5
Past year average comments per pull request: 1.27
Past year merged pull request: 9
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/rails/globalid

Top Issue Authors

  • antulik (2)
  • Drowze (1)
  • nhorton (1)
  • giangbimin (1)
  • junaruga (1)
  • scottbarrow (1)
  • isikyus (1)
  • erikbelusic (1)
  • tsrivishnu (1)
  • sbhatore95 (1)
  • fny (1)
  • rafaelfranca (1)
  • edimossilva (1)
  • intrip (1)
  • romikoops (1)

Top Pull Request Authors

  • dependabot[bot] (14)
  • y-yagi (9)
  • olleolleolle (5)
  • tylerwillingham (5)
  • Earlopain (4)
  • elia (4)
  • nvasilevski (3)
  • alexcwatt (3)
  • voxik (3)
  • georgeclaghorn (3)
  • junaruga (3)
  • berkos (2)
  • duffuniverse (2)
  • m-nakamura145 (2)
  • kaspth (2)

Top Issue Labels

  • help wanted (2)
  • enhancement (1)
  • bug (1)

Top Pull Request Labels

  • dependencies (14)

Package metadata

gem.coop: globalid

URIs for your models makes it easy to pass references around.

rubygems.org: globalid

URIs for your models makes it easy to pass references around.

proxy.golang.org: github.com/rails/globalid

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/rails/globalid#section-documentation
  • Licenses: mit
  • Latest release: v1.4.0 (published about 2 months ago)
  • Last Synced: 2026-08-16T06:04:20.796Z (1 day ago)
  • Versions: 25
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Stargazers count: 1.972%
    • Forks count: 2.449%
    • Average: 6.2%
    • Dependent packages count: 9.576%
    • Dependent repos count: 10.802%
debian-11: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Documentation: https://packages.debian.org/bullseye/ruby-globalid
  • Licenses: mit
  • Latest release: 0.4.2+REALLY.0.3.6-1 (published 6 months ago)
  • Last Synced: 2026-08-01T00:07:29.781Z (17 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-20.04: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 0.4.2+REALLY.0.3.6-1 (published 6 months ago)
  • Last Synced: 2026-03-13T20:20:46.530Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-24.04: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 1.2.1-1 (published 6 months ago)
  • Last Synced: 2026-03-06T15:59:08.401Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-24.10: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 1.2.1-1 (published 6 months ago)
  • Last Synced: 2026-03-09T17:05:48.954Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-13: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Documentation: https://packages.debian.org/trixie/ruby-globalid
  • Licenses: mit
  • Latest release: 1.2.1-2 (published 6 months ago)
  • Last Synced: 2026-08-08T22:03:38.729Z (9 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-22.04: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 0.6.0-1 (published 6 months ago)
  • Last Synced: 2026-03-13T13:36:31.608Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-10: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Documentation: https://packages.debian.org/buster/ruby-globalid
  • Licenses: mit
  • Latest release: 0.4.2+REALLY.0.3.6-1 (published 6 months ago)
  • Last Synced: 2026-03-13T19:03:51.483Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-23.10: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 0.6.0-2 (published 6 months ago)
  • Last Synced: 2026-03-14T02:17:22.729Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
gentoo-portage: dev-ruby/globalid

Reference models by URI

  • Homepage: https://github.com/rails/globalid
  • Documentation: https://packages.gentoo.org/packages/dev-ruby/globalid
  • Licenses: MIT
  • Latest release: 1.4.0 (published 22 days ago)
  • Last Synced: 2026-07-28T01:17:16.918Z (21 days ago)
  • Versions: 4
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
debian-12: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Documentation: https://packages.debian.org/bookworm/ruby-globalid
  • Licenses: mit
  • Latest release: 0.6.0-2 (published 6 months ago)
  • Last Synced: 2026-08-03T06:10:49.089Z (14 days ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%
ubuntu-23.04: ruby-globalid

  • Homepage: https://github.com/rails/globalid
  • Licenses: mit
  • Latest release: 0.6.0-1 (published 6 months ago)
  • Last Synced: 2026-03-11T17:19:47.322Z (5 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 100%

Dependencies

Gemfile rubygems
  • activemodel >= 0
  • railties >= 0
Gemfile.lock rubygems
  • actionpack 6.1.4.1
  • actionview 6.1.4.1
  • activemodel 6.1.4.1
  • activesupport 6.1.4.1
  • builder 3.2.4
  • concurrent-ruby 1.1.9
  • crass 1.0.6
  • erubi 1.10.0
  • globalid 1.0.0
  • i18n 1.8.11
  • loofah 2.18.0
  • method_source 1.0.0
  • mini_portile2 2.6.1
  • minitest 5.14.4
  • nokogiri 1.12.5
  • racc 1.6.0
  • rack 2.2.3.1
  • rack-test 1.1.0
  • rails-dom-testing 2.0.3
  • rails-html-sanitizer 1.4.3
  • railties 6.1.4.1
  • rake 13.0.6
  • thor 1.1.0
  • tzinfo 2.0.4
  • zeitwerk 2.5.1
globalid.gemspec rubygems
  • rake >= 0 development
  • activesupport >= 5.0
.github/workflows/ci.yml actions
  • actions/checkout v3 composite
  • ruby/setup-ruby v1 composite
.devcontainer/Dockerfile docker
  • mcr.microsoft.com/vscode/devcontainers/ruby 0-${VARIANT} build

Score: 33.312648556838234