-
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #15 from anomaly/dto-implementation
Major DTO implementation
- Loading branch information
Showing
154 changed files
with
4,209 additions
and
970 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| --- | ||
| name: Bug report | ||
| about: Create a report to help us improve | ||
| title: '' | ||
| labels: '' | ||
| assignees: '' | ||
|
|
||
| --- | ||
|
|
||
| **Describe the bug** | ||
| A clear and concise description of what the bug is. | ||
|
|
||
| **To Reproduce** | ||
| Steps to reproduce the behavior: | ||
| 1. Go to '...' | ||
| 2. Click on '....' | ||
| 3. Scroll down to '....' | ||
| 4. See error | ||
|
|
||
| **Expected behavior** | ||
| A clear and concise description of what you expected to happen. | ||
|
|
||
| **Screenshots** | ||
| If applicable, add screenshots to help explain your problem. | ||
|
|
||
| **Desktop (please complete the following information):** | ||
| - OS: [e.g. iOS] | ||
| - Browser [e.g. chrome, safari] | ||
| - Version [e.g. 22] | ||
|
|
||
| **Smartphone (please complete the following information):** | ||
| - Device: [e.g. iPhone6] | ||
| - OS: [e.g. iOS8.1] | ||
| - Browser [e.g. stock browser, safari] | ||
| - Version [e.g. 22] | ||
|
|
||
| **Additional context** | ||
| Add any other context about the problem here. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| name: Feature request | ||
| about: Suggest an idea for this project | ||
| title: '' | ||
| labels: '' | ||
| assignees: '' | ||
|
|
||
| --- | ||
|
|
||
| **Is your feature request related to a problem? Please describe.** | ||
| A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] | ||
|
|
||
| **Describe the solution you'd like** | ||
| A clear and concise description of what you want to happen. | ||
|
|
||
| **Describe alternatives you've considered** | ||
| A clear and concise description of any alternative solutions or features you've considered. | ||
|
|
||
| **Additional context** | ||
| Add any other context or screenshots about the feature request here. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| name: Testing | ||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
| pull_request: | ||
| branches: | ||
| - master | ||
|
|
||
| jobs: | ||
| test: | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
| - name: Setup Python | ||
| uses: actions/setup-python@v4 | ||
| with: | ||
| python-version-file: pyproject.toml | ||
| - name: Install Task | ||
| uses: arduino/setup-task@v1 | ||
| with: | ||
| version: 3.x | ||
| repo-token: ${{ secrets.GITHUB_TOKEN }} | ||
| - name: Install dependencies | ||
| run: | | ||
| pip install poetry | ||
| poetry install | ||
| - name: Run tests | ||
| run: | | ||
| export GACC_API_KEY=${{ secrets.GACC_API_KEY }} | ||
| task test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Command Line Interface | ||
|
|
||
| We provide a command line interface to interact with the Gallagher Command Centre. It uses the API client to communicate with the server, which doubly serves as a reference example of how to use the API client. | ||
|
|
||
| > We use [typer](https://typer.tiangolo.com) to construct the CLI, which in turn uses [click](https://click.palletsprojects.com). We also use [rich](https://rich.readthedocs.io/en/stable/) to make the output nicer. The CLI is decoupled from the API client, and is not install by default. | ||
| We follow a `git` like `command`, `sub-command` pattern, so it should feel quite familiar. | ||
|
|
||
| poetry will install the alias `gal` for you to interact with the CLI. You can ask for help with: | ||
|
|
||
| ``` | ||
| gal --help | ||
| ``` | ||
|
|
||
| which will list the available commands: | ||
|
|
||
| ``` | ||
| Usage: gal [OPTIONS] COMMAND [ARGS]... | ||
| ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ | ||
| │ --install-completion Install completion for the current shell. │ | ||
| │ --show-completion Show completion for the current shell, to copy it or customize the installation. │ | ||
| │ --help Show this message and exit. │ | ||
| ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ | ||
| ╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ | ||
| │ alarms list or query alarms in the command centre │ | ||
| │ ch query or manage cardholders │ | ||
| │ events query command centre events │ | ||
| ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ | ||
| ``` | ||
|
|
||
| A simple example to get a list of cardholders looks like: | ||
|
|
||
| ``` | ||
| (gallagher-py3.11) ➜ gallagher git:(dto-implementation) ✗ gal ch list | ||
| Cardholders | ||
| ┏━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓ | ||
| ┃ Id ┃ First name ┃ Last name ┃ Authorised ┃ | ||
| ┡━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩ | ||
| │ 8246 │ Johnetta │ Abdallah │ yes │ | ||
| │ 7936 │ Socorro │ Abrahams │ yes │ | ||
| │ 8374 │ Geoffrey │ Acey │ yes │ | ||
| │ 8370 │ Weldon │ Acuff │ yes │ | ||
| │ 7922 │ Rusty │ Adelsperger │ yes │ | ||
| ``` | ||
|
|
||
| you can also ask each sub command to give you in |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Design | ||
|
|
||
| A central feature to this client is it's detailed design, focused on a superior developer experience and performance. We also ensure that we follow design patterns outlined by Gallagher | ||
|
|
||
| ## Data Transfer Objects | ||
|
|
||
| This a central part of our design. There are three types of schema definitions, each one of them suffixed with their intent: | ||
|
|
||
| - **Ref** are `References` to other objects, they using contain a `href` and possibly additional meta data such as a `name` or `id` | ||
| - **Summary** is what is returned by the Gallagher API in operations such as [searches](https://gallaghersecurity.github.io/cc-rest-docs/ref/cardholders.html), these are generally a subset of the full object | ||
| - **Detail** are the full object found at a particular `href`, they compound on the `Summary` schema and add additional attributes | ||
|
|
||
| I additional we have classes that defined responses which are suffixed with **Response**, these wrap structures which returns `hrefs` for `next` and `previous` responses and usually have a collection to hold the response. | ||
|
|
||
| Ensure that each Endpoint defines their own DTOs so you can test them for authenticity. Avoid writing generic classes. | ||
|
|
||
| While `Refs`, `Summary` and `Detail` responses have fields, and it would make sense from an efficiency point of view to inherit e.g `Summary` builds on `Ref`, this should be avoided so logically an instance of a `Ref` class doesn't assert true for `isinstance` of a `Summary` class. | ||
|
|
||
| ## API Client Core | ||
|
|
||
| The `core` package in `cc` provides two important classes: | ||
|
|
||
| - `APIEndpoint` which all endpoint consumers configuration must inherit from | ||
| - `EndpointConfig` an instance of which each class must return as a result of the `get_config` method | ||
|
|
||
| Every Endpoint Consumer Class is expected to return an instance of `EndpointConfig` from the `get_config` method. Each configuration provides references to paths that are dynamically discovered as part of our bootstrapping process. | ||
|
|
||
| Never hard code URLs as this violates the [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) design principle. | ||
|
|
||
| Additionally each configuration will provide references to DTO classes that is used to parse responses, and details of the body. | ||
|
|
||
| ``` | ||
| class Alarms( | ||
| APIEndpoint | ||
| ): | ||
| """ Alarms | ||
| """ | ||
| @classmethod | ||
| async def get_config(cls) -> EndpointConfig: | ||
| return EndpointConfig( | ||
| endpoint=Capabilities.CURRENT.features.alarms.alarms, | ||
| dto_list=AlarmResponse, | ||
| dto_retrieve=AlarmZoneSummary, | ||
| ) | ||
| ``` | ||
|
|
||
| The above example shows the `Alarms` class which is a consumer of the `alarms` endpoint. It nominates `AlarmResponse` as the class the infrastructure will use to parse `list` responses and `AlarmZoneSummary` as the class to parse `retrieve` responses. | ||
|
|
||
| It references the `Capabilities.CURRENT` singleton which is a `Capabilities` instance that is bootstrapped at runtime. This is a singleton that is used to provide references to all endpoints. | ||
|
|
||
| If a command centre does not have a certain capability then the objects are set to `None` and accessing the feature raises an exception (more on this in other sections). | ||
|
|
||
| ### Designing Endpoints | ||
|
|
||
| ## Layout | ||
|
|
||
| Layout of our files |
Oops, something went wrong.