New Feature
This guide is for writing new features to mirrord, specifically features that introduce new hooks.
Adding a feature (file system, network) can be tricky and there are a lot of edge cases we might need to cover.
In order to have a more structured approach, here’s the flow you should follow when working on such a feature.
- Start with the use case. Write an example use case of the feature, for example “App needs to read credentials from a file”.
- Write a minimal app that implements the use case - so in the case of our example, an app that reads credentials from a file. Start with either Node or Python as those are most common.
- Figure out what functions need to be hooked in order for the behavior to be run through the mirrord-agent instead of locally. We suggest using
strace
. - Write a doc on how you would hook and handle the cases, for example:
- To implement use case “App needs to read credentials from a file*”
- I will hook
open
andread
handling calls only with flags O_RDONLY. - Once
open
is called, I’ll send a blocking request to the agent to open the remote file, returning the return code of the operation. - Create an fd using
memfd
. The result will be returned to the local app, and if successful we’ll save that fd into a HashMap that matches between local fd and remote fd/identifier. - When
read
is called, I will check if the fd being read was previously opened by us, and if it is we’ll send a blockingread
request to the agent. The result will be sent back to the caller. - And so on.
- This doc should go later on to our mirrord docs for advanced developers so people can understand how stuff works
- After approval of the implementation, you can start writing code, and add relevant e2e tests.