mirror of
https://github.com/discourse/discourse.git
synced 2024-11-29 22:33:45 +08:00
12a18d4d55
This commit main goal was to comply with Zeitwerk and properly rely on autoloading. To achieve this, most resources have been namespaced under the `Chat` module. - Given all models are now namespaced with `Chat::` and would change the stored types in DB when using polymorphism or STI (single table inheritance), this commit uses various Rails methods to ensure proper class is loaded and the stored name in DB is unchanged, eg: `Chat::Message` model will be stored as `"ChatMessage"`, and `"ChatMessage"` will correctly load `Chat::Message` model. - Jobs are now using constants only, eg: `Jobs::Chat::Foo` and should only be enqueued this way Notes: - This commit also used this opportunity to limit the number of registered css files in plugin.rb - `discourse_dev` support has been removed within this commit and will be reintroduced later <!-- NOTE: All pull requests should have tests (rspec in Ruby, qunit in JavaScript). If your code does not include test coverage, please include an explanation of why it was omitted. -->
97 lines
3.6 KiB
Ruby
97 lines
3.6 KiB
Ruby
# frozen_string_literal: true
|
||
|
||
module Service
|
||
# Module to be included to provide steps DSL to any class. This allows to
|
||
# create easy to understand services as the whole service cycle is visible
|
||
# simply by reading the beginning of its class.
|
||
#
|
||
# Steps are executed in the order they’re defined. They will use their name
|
||
# to execute the corresponding method defined in the service class.
|
||
#
|
||
# Currently, there are 5 types of steps:
|
||
#
|
||
# * +contract(name = :default)+: used to validate the input parameters,
|
||
# typically provided by a user calling an endpoint. A special embedded
|
||
# +Contract+ class has to be defined to holds the validations. If the
|
||
# validations fail, the step will fail. Otherwise, the resulting contract
|
||
# will be available in +context[:contract]+. When calling +step(name)+ or
|
||
# +model(name = :model)+ methods after validating a contract, the contract
|
||
# should be used as an argument instead of context attributes.
|
||
# * +model(name = :model)+: used to instantiate a model (either by building
|
||
# it or fetching it from the DB). If a falsy value is returned, then the
|
||
# step will fail. Otherwise the resulting object will be assigned in
|
||
# +context[name]+ (+context[:model]+ by default).
|
||
# * +policy(name = :default)+: used to perform a check on the state of the
|
||
# system. Typically used to run guardians. If a falsy value is returned,
|
||
# the step will fail.
|
||
# * +step(name)+: used to run small snippets of arbitrary code. The step
|
||
# doesn’t care about its return value, so to mark the service as failed,
|
||
# {#fail!} has to be called explicitly.
|
||
# * +transaction+: used to wrap other steps inside a DB transaction.
|
||
#
|
||
# The methods defined on the service are automatically provided with
|
||
# the whole context passed as keyword arguments. This allows to define in a
|
||
# very explicit way what dependencies are used by the method. If for
|
||
# whatever reason a key isn’t found in the current context, then Ruby will
|
||
# raise an exception when the method is called.
|
||
#
|
||
# Regarding contract classes, they automatically have {ActiveModel} modules
|
||
# included so all the {ActiveModel} API is available.
|
||
#
|
||
# @example An example from the {TrashChannel} service
|
||
# class TrashChannel
|
||
# include Base
|
||
#
|
||
# model :channel, :fetch_channel
|
||
# policy :invalid_access
|
||
# transaction do
|
||
# step :prevents_slug_collision
|
||
# step :soft_delete_channel
|
||
# step :log_channel_deletion
|
||
# end
|
||
# step :enqueue_delete_channel_relations_job
|
||
#
|
||
# private
|
||
#
|
||
# def fetch_channel(channel_id:, **)
|
||
# Chat::Channel.find_by(id: channel_id)
|
||
# end
|
||
#
|
||
# def invalid_access(guardian:, channel:, **)
|
||
# guardian.can_preview_chat_channel?(channel) && guardian.can_delete_chat_channel?
|
||
# end
|
||
#
|
||
# def prevents_slug_collision(channel:, **)
|
||
# …
|
||
# end
|
||
#
|
||
# def soft_delete_channel(guardian:, channel:, **)
|
||
# …
|
||
# end
|
||
#
|
||
# def log_channel_deletion(guardian:, channel:, **)
|
||
# …
|
||
# end
|
||
#
|
||
# def enqueue_delete_channel_relations_job(channel:, **)
|
||
# …
|
||
# end
|
||
# end
|
||
# @example An example from the {UpdateChannelStatus} service which uses a contract
|
||
# class UpdateChannelStatus
|
||
# include Base
|
||
#
|
||
# model :channel, :fetch_channel
|
||
# contract
|
||
# policy :check_channel_permission
|
||
# step :change_status
|
||
#
|
||
# class Contract
|
||
# attribute :status
|
||
# validates :status, inclusion: { in: Chat::Channel.editable_statuses.keys }
|
||
# end
|
||
#
|
||
# …
|
||
# end
|
||
end
|