This is a library to connect apps built on ruby to Cxf.Cloud
Add gem to the Gemfile
gem 'cxf'
Add the following configuration to the controller and include MintClients and UserAuthHelper (if you log in with a contact, you can use ContactAuthHelper) NOTE: Proxy automatically renew the token, so you don't need to worry about it
if you haven't run the generator yet, you can use after_action to update the token
require 'cxf'
class ApplicationController < ActionController::Base
include CxfClients
include UserAuthHelper # if you log in with a user
include ContactAuthHelper # if you log in with a contact
after_action :update_user_tokens # if you haven't run the generator yet and you log in with a user
after_action :update_contact_tokens # if you haven't run the generator yet and you log in with a contact
end
Using Cxf Public API
cxf_pub = Cxf::Pub.new(cxf_url, api_key)
cxf_pub.get_stories
Using Cxf Contact API
cxf_contact_login(email, password)
@cxf_contact.me
Using Cxf User API
cxf_user_login(email, password)
@cxf_user.get_contacts
Using Cxf User API by Service account
# Usually the api_key and the session token are the same, you can go to the service accounts section
# from your Cxf instance and generate your service account api key
cxf_service_account = Cxf::User.new(cxf_url, api_key, api_key)
cxf_service_account.get_contacts
This command will generate the cxf_config.yml.erb file, API controlles and routes to have available the cxf endpoints
rails generate cxf_files
Your app controller needs to be inherited from Cxf::BaseController
# application_controller.rb
class ApplicationController < Cxf::BaseController
end
This heritance will make the following class variables available:
| Variable | Description |
|---|---|
| @host | Host defined in cxf_config.yml.erb file |
| @api_key | API key defined in cxf_config.yml.erb file |
| @cxf_pub | An already instanced public client |
| @contact_token | A token used by cxf to identify the contact |
| @visit_id | An identifier of the visit registered |
| @cxf_contact | An already instanced contact client (not usable until call the contact login method) |
And the following controller methods:
| Method | Parameters | Return value | Description |
|---|---|---|---|
| cxf_contact_signed_in? | none | boolean | Indicates if the contact has an active session |
| cxf_contact_login | email, password | void | Starts a contact session |
| cxf_contact_logout | none | void | Ends a contact session |
| cxf_contact_magic_link_login | hash, redirect_in_error | void | Starts a contact session in cxf.cloud and set a session cookie |
If want to have a private section where only a cxf user can acces and use the private user api is needed to inherit from the AdminBaseController.
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
end
This heritance will make the following class variables available:
| Variable | Description |
|---|---|
| @host | Host defined in cxf_config.yml.erb file |
| @api_key | API key defined in cxf_config.yml.erb file |
| @cxf_user | An already instanced user client (not usable until call the user login method) |
| @cxf_service_account | An already instanced service_account client |
And the following controller methods:
| Method | Parameters | Return value | Description |
|---|---|---|---|
| cxf_user_login | email, password | void | Starts a user session |
| cxf_user_logout | none | void | Ends a user session |
| cxf_user_signed_in? | none | Boolean | Indicates if the user has an active session |
| cxf_user_magic_link_login | hash | void | Starts a user session in cxf.cloud and set a session cookie |
The cxf.config.yml file allows to set the Cxf instance to which the implementation will access, it can add the host, api key for Cxf, in addition to setting the cache rules with redis, if you want to add a url to cache , you should add it to the groups array and set the cache time.
# Cxf connection configuration
cxf:
host: http://your_host_goes_here.com
api_key: your_cxf_api_key_goes_here
cxf_slug: slug_id #save id and token in redis
redis_cache:
use_cache: boolean_value_to_enable_and_disable_cache
redis_host: your_redis_server_host
redis_port: your_redis_server_port
redis_db: your_redis_database
groups:
- urls:
- group_of_urls
time: time_that_will_be_applied_to_urls_in_seconds
sdk:
debug: false
# Timeout is specified in seconds
default_http_timeout: 30 # Allows setting a default timeout for all HTTP calls.
get_http_timeout: 30 # Allows setting a default timeout for all GET calls.
post_http_timeout: 30 # Allows setting a default timeout for all POST calls.
put_http_timeout: 30 # Allows setting a default timeout for all PUT calls.
delete_http_timeout: 30 # Allows setting a default timeout for all DELETE calls.
To enable sdk debugging you can change the variable debug. Finally, to configure the sharing of cookies between domains, you can configure the "iframe cookies", where you establish how long the cookie will have, if it is activated and the domains to share cookies (to have this functionality, we recommend the use of the template).
# Cxf connection configuration
sdk:
debug: false
cookies_iframe:
activated: boolean_value_to_enable_and_disable_cookies_iframe
expire_time: expire_time_of_cookies_iframe_in_hours
hosts:
- array_of_host_to_send_cookies
If you want other clients for admin/base controller, you need to specify them with the "define_cxf_clients" method
Example:
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
def define_cxf_clients
%w[contact user pub service_account]
end
end
If you want specific timeouts per instance, you can define cxf_sdk_timeouts_config
Example:
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
def cxf_sdk_timeouts_config
{
default: 30,
get: 50,
post: 40,
put: 30,
delete: 10
}
end
end
The SDK provides different errors that are identified according to the response provided by Cxf, the errors can be 404, 401, 422, 500, etc. To rescue these errors, it is done as follows:
# Example 1
begin
@cxf_pub.client.raw('/invalid-url')
rescue => Cxf::Errors::ResourceNotFoundException
puts "Error 404"
end
# Example 2
begin
response = @cxf_contact.register(data)
rescue Cxf::Errors::ValidationException => e
response = e.to_h
# This will return a Hash with the information needed to debug
# Example:
{
:client => sdk_instance,
# Client instance
# @host = "https://your_cxf_instance",
# @api_key = current_api_key,
# @session_token = current_session_token,
# @contact_token_id = current_contact_token_id,
# @visit_id = current_visit_id,
# @debug = current_debug_flag,
# @scope = current_scope,
# @base_url = current_base_url
:title => "Request failed with status 422",
:detail => "Unprocessable Entity",
:http_status => 422,
:response => { "email" => ["The email has already been taken."] },
:errors => ["The email has already been taken."]
}
end
The current errors are:
| Error | Status | Full error name |
|---|---|---|
| AccessDeniedException | 401 | Cxf::Errors::AccessDeniedException |
| ResourceNotFoundException | 404 | Cxf::Errors::ResourceNotFoundException |
| MethodNotAllowedException | 405 | Cxf::Errors::MethodNotAllowedException |
| ValidationException | 422 | Cxf::Errors::ValidationException |
| InternalServerException | 500 | Cxf::Errors::InternalServerException |
Cxf::Pub::Config
Cxf::Pub::Content
Cxf::Pub::Ecommerce
Cxf::Contact::Config
Cxf::Contact::Content
Cxf::Contact::Ecommerce
Cxf::User::Config
Cxf::User::Crm
Cxf::User::Ecommerce
FAQs
Unknown package
We found that cxf demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.