{"id":13747637,"url":"https://github.com/afcapel/alondra","last_synced_at":"2025-05-09T09:30:40.624Z","repository":{"id":48771807,"uuid":"2082434","full_name":"afcapel/alondra","owner":"afcapel","description":"Push server and framework that adds real time capabilities to your rails apps","archived":true,"fork":false,"pushed_at":"2021-07-12T20:33:57.000Z","size":532,"stargazers_count":88,"open_issues_count":18,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-12T01:20:30.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afcapel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-21T08:31:57.000Z","updated_at":"2023-03-26T16:51:12.000Z","dependencies_parsed_at":"2022-08-26T22:12:26.057Z","dependency_job_id":null,"html_url":"https://github.com/afcapel/alondra","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Falondra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Falondra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Falondra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Falondra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afcapel","download_url":"https://codeload.github.com/afcapel/alondra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224849349,"owners_count":17380101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T06:01:35.904Z","updated_at":"2024-11-15T21:30:45.940Z","avatar_url":"https://github.com/afcapel.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Alondra\n\nAlondra is a push server and framework that adds real time capabilities to\nyour rails applications.\n\n## What can I do with Alondra?\n\n### Subscribe clients to channels\n\nAlondra allows browsers to subscribe to channels. Any Ruby process that loads\nyour Rails environment will be able to push messages to those channels.\n\nTo subscribe to a channel you can use the built in helper:\n\n```\n  \u003c%= alondra_client @chat %\u003e\n```\n\nAlondra uses [conventions to map records and classes to channel names](https://github.com/afcapel/alondra/wiki/Event-conventions).\nThe last example will subscribe the browser to a channel named '/chats/:chat_id'.\nThen, the Alondra client will render any message pushed to that channel.\n\nIf you don't want to use Alondra conventions, you can always provide your own\nchannel names:\n\n```\n  \u003c%= alondra_client ['my custom channel', 'another channel'] %\u003e\n```\n\n### Sending push notifications\n\nSince Alondra is all Ruby and integrates with your Rails environment, you can\nuse your Rails models and views to render push messages. For example, sending\na push notification from your controller action is as simple as this:\n\n```ruby\n  def create\n    @chat = Chat.find(params[:chat_id])\n    @message = @chat.messages.build(params[:message])\n\n    if @message.save\n      push '/messages/create', :to =\u003e @chat\n    end\n\n    respond_with @message\n  end\n```\n\nThis will render the '/messages/create' view and send the results to all\nclients subscribed to the chat channel.\n\nYou can send push notifications from any process that loads your Rails\nenvironment and from any class that includes the Alondra::Pushing module.\nWhen rendering a push message the local context (that is, the instance\nvariables of the caller object) will be available in the view.\n\n### Listening to events\n\nAlondra comes bundled with an EventListener class that allows you to react to\nevents such as when a client subscribes to a channel.\n\n```ruby\n  # A ChatListener will by default listen to events\n  # sent to any channel whose name begins with '/chat'\n  class ChatListener \u003c Alondra::EventListener\n\n    # If you want to listen to other channels than the default ones\n    # you can specify other patterns with the listen_to method, like\n    #\n    # listen_to  /tion$/\n    #\n    # That would make your listener receive events from any channel whose\n    # name ends in 'ion'\n\n\n    # This will be fired any time a client subscribes to\n    # any of the observed channels\n    on :subscribed, :to =\u003e :member do\n\n      # If you use Cookie Based Session Store,\n      # you can access the Rails session from the listener\n      @user = User.find(session[:user_id])\n\n      # Push notifications from listener\n      push '/users/user', :to =\u003e channel_name\n    end\n  end\n```\n\nYou can also listen to :unsubscribe, :created, :updated, :destroyed or any\ncustom event in the observed channels.\n\n### Push record changes to the client\n\nSometimes you are just interested in pushing record updates to subscribed\nclients. You can do that annotating your model:\n\n```ruby\n  class Presence \u003c ActiveRecord::Base\n    belongs_to :user\n    belongs_to :chat\n\n    push :changes, :to =\u003e :chat\n  end\n```\n\nThis will push an event (:created, :upated or :destroyed)  to the chat channel\neach time a Message instance changes.\n\nIn the client you can listen to these events using the JavaScript API:\n\n```javascript\n\n  var alondraClient = new AlondraClient('localhost', 12345, ['/chat_rooms/1']);\n\n  // render user name when presence is created\n\n  $(alondraClient).bind(\"created.Presence\", function(event, resource){\n    if( $('#user_'+resource.user_id).length == 0 ){\n      $('#users').append(\"\u003cli id='user_\" + resource.user_id + \"'\u003e\" + resource.username + \"\u003c/li\u003e\");\n    }\n  });\n\n  // remove user name when presence is destroyed\n\n  $(alondraClient).bind(\"destroyed.Presence\", function(event, resource){\n    $('#user_'+resource.user_id).remove();\n  });\n\n```\n\nThis technique is especially useful if you use something like Backbone.js\nto render your app frontend.\n\n\n## Example application\n\nYou can check the [example application](http://github.com/afcapel/alondra-example)\nto see how some of the features are used.\n\n## Installation\n\nCurrently Alondra depends on Rails 3.1 and Ruby 1.9. It also uses ZeroMQ for\ninterprocess communication, so you need to install the library first. If\nyou are using Homebrew on Mac OS X, just type\n\n\u003cpre\u003e\n  brew install zeromq\n\u003c/pre\u003e\n\nWhen ZeroMQ is installed, add the Alondra gem to your Gemfile.\n\n\u003cpre\u003e\n  gem \"alondra\"\n\u003c/pre\u003e\n\nYou also will need to install the server initialization script into your app.\nIn the shell execute the generator.\n\n\u003cpre\u003e\n  $ rails g alondra install\n\u003c/pre\u003e\n\nTo run the Alondra server, just call the provided executable in your project directory\n\n\u003cpre\u003e\n  $ bundle exec alondra\n\u003c/pre\u003e\n\nIn development mode you can also run the Alondra server in its own thread.\nSee the [initializer in the example application](https://github.com/afcapel/alondra-example/blob/master/config/initializers/alondra_server.rb)\nfor how to do it.\n\n## Contributors\n\n- [Ryan LeCompte](http://github.com/ryanlecompte)\n- [Jaime Iniesta](http://github.com/jaimeiniesta)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafcapel%2Falondra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafcapel%2Falondra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafcapel%2Falondra/lists"}