mirror of
https://github.com/discourse/discourse.git
synced 2024-12-14 14:25:59 +08:00
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
|