// file : mod/ci-common.hxx -*- C++ -*- // license : MIT; see accompanying LICENSE file #ifndef MOD_CI_COMMON_HXX #define MOD_CI_COMMON_HXX #include // database #include #include #include #include #include namespace brep { class ci_start { public: void init (shared_ptr); // If the request handling has been performed normally, then return the // information that corresponds to the CI result manifest (see CI Result // Manifest in the manual). Otherwise (some internal error has occured), // log the error and return nullopt. // // The arguments correspond to the CI request and overrides manifest // values (see CI Request and Overrides Manifests in the manual). Note: // request id and timestamp are generated by the implementation. // struct package { package_name name; optional version; }; // Note that the inability to generate the reference is an internal // error. Thus, it is not optional. // // Note that if the CI request information is persisted to the database // (which, depending on the CI request handler, may not be the case), then // the reference is assumed to be the respective tenant id. // struct start_result { uint16_t status; string message; string reference; vector> custom_result; }; // In the optional tenant service information, if service id is empty, // then the generated tenant id is used instead. // // Note that if the tenant service is specified, then the CI request // information is expected to be persisted to the database and thus // start_result::reference denotes the tenant id in this case (see above // for details). // optional start (const basic_mark& error, const basic_mark& warn, const basic_mark* trace, optional&&, const repository_location& repository, const vector& packages, const optional& client_ip, const optional& user_agent, const optional& interactive = nullopt, const optional& simulate = nullopt, const vector>& custom_request = {}, const vector>& overrides = {}) const; // Create an unloaded CI request returning tenant id on success and // nullopt on an internal error. Such a request is not started until // loaded with the load() function below. Configure the time interval // between the build_unloaded() notifications for the being created tenant // and set the initial delay for the first notification. See also the // build_unloaded() tenant services notification. // // The duplicate_tenant_mode argument specifies the behavior in case of // the duplicate tenant_service type/id pair. The default is to fail by // throwing an exception. Alternatively, this can be ignored or the // previous tenant can be canceled (thus freeing the type/id pair; see // below) and a new tenant with the same type/id created. In both these // modes (ignore and replace), the second half of the returned pair // indicates whether there was a duplicate. If there were, then for the // ignore mode the returned tenant id corresponds to the old tenant and // for the replace mode -- to the new tenant. // // The replace_archived mode is a variant of replace that replaces if the // tenant is already archived and ignores it otherwise (with the result // having the same semantics as in the replace and ignore modes). // // Note also that the duplicate_tenant_mode::replace modes are not the // same as separate calls to create() and then to cancel() since the // latter would happen in two separate transactions and will thus be // racy. @@@ TODO // // Note: should be called out of the database transaction. // enum class duplicate_tenant_mode {fail, ignore, replace, replace_archived}; enum class duplicate_tenant_result {created, ignored, replaced}; pair, duplicate_tenant_result> create (const basic_mark& error, const basic_mark& warn, const basic_mark* trace, odb::core::database&, tenant_service&&, duration notify_interval, duration notify_delay, duplicate_tenant_mode = duplicate_tenant_mode::fail) const; // Load (and start) previously created (as unloaded) CI request. Similarly // to the start() function, return nullopt on an internal error. // // Note that tenant_service::id is used to identify the CI request tenant. // // Note: should be called out of the database transaction. // optional load (const basic_mark& error, const basic_mark& warn, const basic_mark* trace, odb::core::database&, tenant_service&&, const repository_location& repository) const; // Cancel previously created or started CI request. Return the service // state or nullopt if there is no tenant for such a type/id pair. // // Specifically, this function clears the tenant service state (thus // allowing reusing the same service type/id pair in another tenant) and // archives the tenant, unless the tenant is unloaded, in which case it is // dropped (@@@ TODO). Note that the latter allow using unloaded tenants // as a relatively cheap asynchronous execution mechanism. // // Note: should be called out of the database transaction. // optional cancel (const basic_mark& error, const basic_mark& warn, const basic_mark* trace, odb::core::database&, const string& type, const string& id) const; // Cancel previously created or started CI request. Return false if there // is no tenant for the specified tenant id. Note that the reason argument // is only used for tracing. // // Similarly to above, this function archives the tenant, unless the // tenant is unloaded, in which case it is dropped (@@@ TODO). Note, // however, that this version does not touch the service state (use the // above version if you want to clear it). // // Note: should be called out of the database transaction. // bool cancel (const basic_mark& error, const basic_mark& warn, const basic_mark* trace, const string& reason, odb::core::database&, const string& tenant_id) const; // Helpers. // // Serialize the start result as a CI result manifest. // static void serialize_manifest (const start_result&, ostream&, bool long_lines = false); private: shared_ptr options_; }; } #endif // MOD_CI_COMMON_HXX