https://github.com/rails/globalid

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

Keywords from Contributors

activerecord activejob mvc rubygems rack rspec feature-flag background-jobs ruby-gem sidekiq

Last synced: about 21 hours ago
JSON representation

Repository metadata

Identify app models with a URI

Host: GitHub
URL: https://github.com/rails/globalid
Owner: rails
License: mit
Created: 2014-08-15T14:05:35.000Z (over 11 years ago)
Default Branch: main
Last Pushed: 2025-10-22T19:48:40.000Z (4 months ago)
Last Synced: 2026-02-23T15:31:27.390Z (8 days ago)
Language: Ruby
Size: 326 KB
Stars: 1,261
Watchers: 24
Forks: 132
Open Issues: 8
Releases: 23
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: MIT-LICENSE

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.
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">

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:

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

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 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

Name: Ruby on Rails
Login: rails
Email:
Kind: organization
Description:
Website: https://rubyonrails.org/
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/4223?v=4
Repositories: 116
Last ynced at: 2023-04-09T03:40:20.529Z
Profile URL: https://github.com/rails

GitHub Events

Total

Release event: 1
Pull request event: 13
Fork event: 10
Issues event: 11
Watch event: 46
Issue comment event: 16
Push event: 11
Pull request review comment event: 5
Pull request review event: 6
Create event: 1

Last Year

Release event: 1
Pull request event: 10
Fork event: 4
Issues event: 8
Watch event: 19
Issue comment event: 11
Push event: 11
Pull request review comment event: 5
Pull request review event: 6
Create event: 1

Committers metadata

Last synced: 2 days ago

Total Commits: 277
Total Committers: 71
Avg Commits per committer: 3.901
Development Distribution Score (DDS): 0.776

Commits in past year: 15
Committers in past year: 6
Avg Commits per committer in past year: 2.5
Development Distribution Score (DDS) in past year: 0.533

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
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
Petrik	p**k@d**t	2
Olle Jonsson	o**n@g**m	2
Nikita Vasilevsky	n**y@s**m	2
Larry Lv	l**0@g**m	2
Jose Rafael Coello Alba	r**o@f**m	2
Jamie Lawrence	j**e@i**m	2
George Claghorn	g**e@b**m	2
Eugene Kenny	e**y@g**m	2
Elia Schito	e**a@s**e	2
Earlopain	1****n	2
Bradley Buda	b**a@g**m	2
Alex Watt	a**x@a**m	2
Aaron Patterson	t**e@r**g	2
Thomas Drake-Brockman	t**m@s**m	2
Adrianna Chang	a**g@s**m	1
and 41 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 6 days ago

Total issues: 43
Total pull requests: 113
Average time to close issues: 6 months
Average time to close pull requests: 2 months
Total issue authors: 42
Total pull request authors: 60
Average comments per issue: 3.65
Average comments per pull request: 1.69
Merged pull request: 71
Bot issues: 0
Bot pull requests: 14

Past year issues: 4
Past year pull requests: 14
Past year average time to close issues: N/A
Past year average time to close pull requests: 13 days
Past year issue authors: 4
Past year pull request authors: 6
Past year average comments per issue: 1.25
Past year average comments per pull request: 0.57
Past year merged pull request: 1
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)
ravicious (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)
voxik (3)
nvasilevski (3)
alexcwatt (3)
junaruga (3)
georgeclaghorn (3)
m-nakamura145 (2)
berkos (2)
kaspth (2)
duffuniverse (2)

Top Issue Labels

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

Top Pull Request Labels

dependencies (14)

Package metadata

Total packages: 13
Total downloads:
- rubygems: 1,188,529,632 total
Total docker downloads: 1,630,402,288
Total dependent packages: 37 (may contain duplicates)
Total dependent repositories: 514,218 (may contain duplicates)
Total versions: 82
Total maintainers: 12
Total advisories: 1

gem.coop: globalid

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

Homepage: http://www.rubyonrails.org
Documentation: http://www.rubydoc.info/gems/globalid/
Licenses: MIT
Latest release: 1.3.0 (published 5 months ago)
Last Synced: 2026-02-28T16:30:30.580Z (3 days ago)
Versions: 24
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 594,198,560 Total
Docker Downloads: 815,201,144
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.013%
- Downloads: 0.038%
Maintainers (12)
- tenderlove
- webster132
- guilleiguaran
- fxn
- cantoniodasilva
- rafaelfranca
- jeremydaer
- matthewd
- eileencodes
- byroot
- jhawthorn
- kamipo

rubygems.org: globalid

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

Homepage: http://www.rubyonrails.org
Documentation: http://www.rubydoc.info/gems/globalid/
Licenses: MIT
Latest release: 1.3.0 (published 5 months ago)
Last Synced: 2026-03-01T09:59:24.597Z (2 days ago)
Versions: 24
Dependent Packages: 37
Dependent Repositories: 514,218
Downloads: 594,331,072 Total
Docker Downloads: 815,201,144
Rankings:
- Dependent repos count: 0.03%
- Downloads: 0.039%
- Docker downloads count: 0.148%
- Dependent packages count: 0.685%
- Average: 0.847%
- Stargazers count: 1.791%
- Forks count: 2.388%
Maintainers (12)
- jhawthorn
- tenderlove
- kamipo
- byroot
- webster132
- guilleiguaran
- fxn
- cantoniodasilva
- rafaelfranca
- jeremydaer
- matthewd
- eileencodes
Advisories:
- ReDoS based DoS vulnerability in GlobalID

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

Homepage:
Documentation: https://pkg.go.dev/github.com/rails/globalid#section-documentation
Licenses: mit
Latest release: v1.3.0 (published 5 months ago)
Last Synced: 2026-02-27T22:04:57.445Z (4 days ago)
Versions: 24
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%

ubuntu-22.04: ruby-globalid

Homepage: https://github.com/rails/globalid
Licenses:
Latest release: 0.6.0-1 (published 18 days ago)
Last Synced: 2026-02-13T13:17:37.327Z (18 days 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:
Latest release: 1.2.1-1 (published 25 days ago)
Last Synced: 2026-02-06T15:13:20.225Z (25 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

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 20 days ago)
Last Synced: 2026-02-13T04:21:48.623Z (19 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 21 days ago)
Last Synced: 2026-02-11T06:40:14.324Z (21 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.10: ruby-globalid

Homepage: https://github.com/rails/globalid
Licenses:
Latest release: 0.6.0-2 (published 18 days ago)
Last Synced: 2026-02-13T18:21:07.404Z (18 days 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:
Latest release: 1.2.1-1 (published 22 days ago)
Last Synced: 2026-02-09T16:36:46.032Z (22 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

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 21 days ago)
Last Synced: 2026-02-13T08:20:38.435Z (18 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:
Latest release: 0.4.2+REALLY.0.3.6-1 (published 19 days ago)
Last Synced: 2026-02-13T07:14:25.436Z (19 days 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:
Latest release: 1.2.1-2 (published 19 days ago)
Last Synced: 2026-02-13T13:16:02.280Z (18 days ago)
Versions: 1
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:
Latest release: 0.6.0-2 (published 19 days ago)
Last Synced: 2026-02-12T23:30:16.403Z (19 days 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.1684715393819