# Switching to new Discovery Handler design
Documentation on how to create a new `DiscoveryHandler` for Akri from the context of someone who has created one using the old design.
## Creating your DiscoveryHandler
Follow the [extensibility doc](https://github.com/deislabs/akri/blob/main/docs/extensibility.md), and use `cargo generate` to create the Discovery Handler package. Then, port your discovery functionality into the `discover` function. This package should live at `akri/discovery-handler-modules`.

Changes to consider:
1. The main change is that instead of discover being periodically called by the Agent, a bidirectional stream is created and it is up to the DiscoveryHandler when to notify the Agent of device visibility changes.
2. Information is passed to the DiscoveryHandler in the string [`DiscoverRequest::discovery_details`](https://sourcegraph.com/github.com/deislabs/akri/-/blob/discovery-utils/src/discovery/v0.rs#L36), which is the same string that is set in a [Configuration](https://sourcegraph.com/github.com/deislabs/akri/-/blob/shared/src/akri/configuration.rs#L30). The DiscoveryHandler should know how to parse this string to get information. For example, the udev `DiscoveryHandler` expects `discovery_details` to be serialized YAML of [its `UdevDiscoveryDetails` struct](https://sourcegraph.com/github.com/deislabs/akri/-/blob/discovery-handlers/udev/src/discovery_handler.rs#L52). It's [Helm template](https://sourcegraph.com/github.com/deislabs/akri/-/blob/deployment/helm/templates/udev.yaml#L9) cleanly serializes the struct using `|+`.
3. All together, your PR should consist of (the equivalent for udev is linked as examples for each):
- [A `DiscoveryHandler` package](https://sourcegraph.com/github.com/deislabs/akri/-/tree/discovery-handler-modules/udev-discovery-handler) in `akri/discovery-handler-modules` that implements Akri's [`DiscoveryHandler` interface](https://sourcegraph.com/github.com/deislabs/akri/-/blob/discovery-utils/proto/discovery.proto#L32) and registers with the Agent, the latter funtionality is abstracted away by the call to `akri_discovery_utils::discovery::discovery_handler::run_discovery_handler` in the generated `DiscoveryHandler` template.
- [A Helm template](https://sourcegraph.com/github.com/deislabs/akri/-/blob/deployment/helm/templates/udev.yaml) for creating Configurations that use your `DiscoveryHandler`
- [A Helm template](https://sourcegraph.com/github.com/deislabs/akri/-/blob/deployment/helm/templates/udev-discovery-handler.yaml) for deploying your `DiscoveryHandler` as a DaemonSet
- [A Dockerfile](https://sourcegraph.com/github.com/deislabs/akri/-/blob/build/containers/Dockerfile.udev-discovery) for your `DiscoveryHandler` image
- A workflow for building your `DiscoveryHandler`. Current `DiscoveryHandlers` do not have these, yet, as the Agent is being deployed will all embedded. This will change soon, as the prevailing Agent will be `slim`. This can be a vNext.
- (optional) a broker and associated Dockerfile and workflow
- Documentation on how to use your `DiscoveryHandler` -- in particular how to choose settings in `discovery_details` -- in `akri/docs/dhname_configuration.md`.

## Embedding the DiscoveryHandler in the Agent
Rust `DiscoveryHandlers` can be conditionally compiled into the Agent, so as to enable a lower footprint scenario where extra DiscoveryHandler pods are not run. If you would like to enable this, there are a few extra steps that need to be taken. To enable embedding the `DiscoveryHandler` in the Agent:
1. Move the `DiscoveryHandler` into a library and place it under the `akri/discover-handlers` directory. Then, import this `DiscoveryHandler` in the`main` function of your package you made in the previous step. Reference the current `DiscoveryHandlers` for examples.
2. In the [Agent's `Cargo.toml`](https://sourcegraph.com/github.com/deislabs/akri/-/blob/agent/Cargo.toml#L14), import your `DiscoveryHandler` as a dependency and [create a feature](https://sourcegraph.com/github.com/deislabs/akri/-/blob/agent/Cargo.toml#L62) for it so it can be conditionally compiled in. Do not make it default compile in.
3. Add the `DiscoveryHandler` to the Agent's `DiscoveryHandler` map as an "embedded" `DiscoveryHandler `[in `inner_register_embedded_discovery_handlers`](https://sourcegraph.com/github.com/deislabs/akri/-/blob/agent/src/util/registration.rs#L226).
4. Add your discovery handler to [`inner_get_discovery_handler`](https://sourcegraph.com/github.com/deislabs/akri/-/blob/agent/src/util/embedded_discovery_handlers.rs#L26). Now, when a Configuration requests your `DiscoveryHandler` a connection will be made.