You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -30,30 +30,94 @@ To run the tests run the command
30
30
make test
31
31
```
32
32
33
+
## Plugins
33
34
34
-
## Usage
35
-
To use sunfishcorelib you need to specify the **configuration parameters** into the conf.json file, an example could be:
35
+
The Sunfish core library uses a plugin based mechanism for providing custom implementation of:
36
+
37
+
- Storage backends: implementation of the Sunfish storage interface used for controlling how RedFish storage are persisted. Plugins in this class must implement the `BackendInterface` class in `storage.backend_interface`.
38
+
- Event handlers: Sunfish interactions with hardware agents and clients is implemented through RedFish events. When an event is received, users might want to execute a specific action depending on the specific event. These are provided via this plugin. Plugins in this class must implement the `EventHandlerInterface` class in `events.event_handler_interface`.
39
+
- Objects handlers: Whenever a request for an object (get, create, replace, patch, delete) is received on the Sunfish external api the core library checks whether a special handler is to be executed for that specific object. Examples are an object is created and it requires other objects to be created in turn as a result. Plugins in this class must implement the `ObjectHandlerInterface` class in `lib.object_handler_interface`.
40
+
- Objects managers: Sunfish keeps all objects in the form of a RedFish tree. Objects belong to a manager (e.g., a Sunfish agent) and this plugin provides the methods for Sungish to interact with the manager. Plugins in this class must implement the `ObjectManagerInterface` class in `lib.object_manager_interface`.
41
+
42
+
Plugins are based on python's namespaced packages and are required to be placed in a specific folder at the top of your project. Only the actual plugins have a user defined name. Please see the below example.
43
+
44
+
```commandline
45
+
─ sunfish_plugins
46
+
├── storage
47
+
│ └──my_storage_package <--- User defined
48
+
│ ├── __init__.py
49
+
│ └── my_storage_backend.py
50
+
└── events_handlers
51
+
│ └──my_handler_package <--- User defined
52
+
│ ├── __init__.py
53
+
│ └── my_handler.py
54
+
├── objects_handlers
55
+
│ └──my_objects_handler_package <--- User defined
56
+
│ ├── __init__.py
57
+
│ └── my_objects_handler.py
58
+
├── objects_managers
59
+
│ └──my_objects_manager_package <--- User defined
60
+
│ ├── __init__.py
61
+
│ └── my_objects_manager.py
36
62
```
37
-
{
38
-
"storage_backend": "FS",
63
+
64
+
Please note no setup.py or project.toml should be placed in any of the plugins folders, including the pre-defined folders (i.e., sunfish_plugins, storage, events_handlers, objects_handlers, objects_managers). Failing to do so will make the plugins impossible to be discovered.
65
+
66
+
67
+
When initializing the library, users can specify their implementation of their plugins as part of the sunfish configuration as described in the [Initialization](https://github.com/OpenFabrics/sunfish_library_reference?tab=readme-ov-file#usage) section.
68
+
69
+
```python
70
+
sunfish_config = {
71
+
72
+
}
73
+
```
74
+
75
+
This plugin mechanism allows user to modify the standard behavior of Sunfish without having to modify the core library. Users can place the `sunifsh_plugins` folder at the top of their project that imports the sunfish core library and benefit from the flexibility of a plugin.
76
+
77
+
If no plugins are specified in the configuration, the Sunfish library will load the default implementations. See the code for more details.
78
+
79
+
## Usage
80
+
81
+
### Initialization
82
+
When initializing the sunfish core library, users need to specify the **configuration parameters** as a dict to be passed to the `init` function. The below snippet shows all the possible fields and how to initialize the library:
-_storage_backend_ specifies the persistency implementation that you want to use
53
-
-_redfish_root_ specifies the Redfish version that must be included in all the requests
54
-
-_backend_conf[fs_root]_ specifies the root directory of Redfish objects' file system
55
-
-_subscription_handler_ specifies the type of handler implementation that you want to use to handle subscriptions
56
-
-_event_handler_ specifies the type of handler implementation that you want to use to handle events
112
+
Where:
113
+
-`redfish_root`: the root of the RedFish service served by the Sunfish core library.
114
+
-`subscripition_hadler`: Identifies how to handle subscriptions to events. At the moment only `redfish` is supported and follows the Redfish standard
115
+
-`storage_backend`: specifies the storage plugin to load.
116
+
-`events_handler`: specifies the event handling plugin to load.
117
+
-`objects_handler`: specifies the object handling plugin to load.
118
+
-`objects_manager`: specifies the object manager plugin to load.
119
+
120
+
All plugins must specify the module and class name via the `module_name` and `class_name` fields respectively.
57
121
58
122
Sunfish should be installed and imported in an existing Python project. To use it:
59
123
- instantiate an object Core(conf)
@@ -62,5 +126,34 @@ Sunfish should be installed and imported in an existing Python project. To use i
62
126
63
127
**IMPORTANT:** this Library assumes that the .json object are legal and well-formed according to the Redfish specification.
64
128
129
+
### Interacting with Sunfish
130
+
131
+
The Sunfish library is meant to be integrated into another software such as a REST server or similar application providing external access to the library.
132
+
Besides the the configuration described above, an application using this library interacts with Sunfish via the below API:
133
+
134
+
```python
135
+
#get an object from the Sunfish tree
136
+
get_object(self, path: string)
137
+
138
+
#create a new object in the Sunfish tree
139
+
create_object(self, path: string, payload: dict)
140
+
141
+
#fully replace an existing object
142
+
replace_object(self, path: str, payload: dict)
143
+
144
+
#patch an existing object
145
+
patch_object(self, path: str, payload: dict)
146
+
147
+
#delete an existing object
148
+
delete_object(self, path: string)
149
+
150
+
#process a Redfish event
151
+
handle_event(self, payload)
152
+
```
153
+
154
+
THe above API is exposed by the `Core` class. More details on the above api are available [here](https://github.com/OpenFabrics/sunfish_library_reference/blob/main/sunfish/lib/core.py).
155
+
156
+
An example REST server, showing how to interact with the Sunfish library is available [here](https://github.com/OpenFabrics/sunfish_server_reference).
157
+
65
158
## License and copyright attribution
66
159
The code in this project is made available via the BSD 3-Clause License. See [LICENSE](https://github.com/OpenFabrics/sunfish_library_reference/blob/main/LICENSE) to access the full license terms. This project adopts the Developer Certificate of Origin (DCO) to certify that each commit was written by the author, or that the author has the rights necessary to contribute the code. All commits must include a DCO which looks like this: Signed-off-by: Joe Smith <joe.smith@email.com>. Specifically, we utilize the [Developer Certificate of Origin Version 1.1] (https://github.com/OpenFabrics/sunfish_library_reference/blob/main/DCO). The project requires that the name used is your real name. Neither anonymous contributors nor those utilizing pseudonyms will be accepted.
0 commit comments