nuts_container/
service.rs

1// MIT License
2//
3// Copyright (c) 2024 Robin Doer
4//
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to
7// deal in the Software without restriction, including without limitation the
8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9// sell copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11//
12// The above copyright notice and this permission notice shall be included in
13// all copies or substantial portions of the Software.
14//
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21// IN THE SOFTWARE.
22
23use nuts_backend::Backend;
24
25use crate::error::Error;
26use crate::migrate::Migration;
27use crate::Container;
28
29/// A service running on top of a [`Container`].
30///
31/// A concrete service should implement this trait. Later, such a service can
32/// be instantiated with [`Container::open_service`] resp.
33/// [`Container::create_service`].
34pub trait Service<B: Backend> {
35    /// The migration assiciated with this service.
36    type Migration: Migration + 'static;
37
38    /// The service identifier.
39    ///
40    /// This is a number that identifies the service, which must be greater
41    /// than `0`.
42    ///
43    /// The sid is stored in the header of the container. When opening a
44    /// service the stored sid must match with this sid, otherwise the open
45    /// attempt is rejected.
46    fn sid() -> u32;
47
48    /// Returns `true` if the service requires a top-id.
49    ///
50    /// If a top-id is required, a top-id is aquired and stored in the header
51    /// of the container when creating a
52    /// [service-instance](Container::create_service).
53    fn need_top_id() -> bool;
54
55    /// Returns the migration assiciated with this service.
56    fn migration() -> Self::Migration;
57}
58
59/// Factory used to instantiate a [service](Service).
60pub trait ServiceFactory<B: Backend> {
61    /// The service
62    type Service: Service<B>;
63
64    /// Error returned by [`Self::open`] and [`Self::create`].
65    ///
66    /// It must be possible to put an [`Error`] instance into this error.
67    type Err: From<Error<B>>;
68
69    /// Create a [service](Service) instance.
70    ///
71    /// Called by [`Container::create_service`] the method should create a new
72    /// [`Self::Service`] instance. The created [container](Container) is
73    /// passed to this method.
74    fn create(container: Container<B>) -> Result<Self::Service, Self::Err>;
75
76    /// Open a [service](Service).
77    ///
78    /// Called by [`Container::open_service`] the method should open an
79    /// existing [`Self::Service`] instance. The opened [container](Container)
80    /// is passed to this method.
81    fn open(container: Container<B>) -> Result<Self::Service, Self::Err>;
82}
nuts_container/service.rs

nuts_container/
service.rs
