numenor-labs/dsfx
2
0
Fork 0
mirror of https://git.numenor-labs.us/dsfx.git synced 2025-04-29 08:10:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
dsfx/docs/internals/hacking.md

5.4 KiB
Raw Blame History

Hacking

Welcome fellow hacker! This document is intended to help you get started with the codebase and understand how to use the various tools and libraries that are included. If you have any questions, please feel free to reach out to the maintainers.

Index

File Structure

There are three folders on the top level of the project. They are:

Files that are stored in the root of the project are generally used for configuration and documentation purposes, but we try to keep the number of files in the root of the project to a minimum.

Currently we have the following files in the top level:

  • .gitignore - This file is used to tell git which files and directories to ignore when committing changes to the repository.
  • CHANGELOG.md - This file is used to keep track of changes made to the codebase. It is currently unused and reserved for future use.
  • go.mod - This file is used to manage the dependencies of the project. It is used by the Go module system to track the dependencies of the project and ensure that the correct versions are used. Our project does not have any external dependencies, so this file primarily serves to establish the project as a Go module.
  • README.md - This file is used to provide information about the project. It is used to document the project and provide instructions for how to use it. This file is intended to be used as a reference for developers and users of the project.

cmd

The cmd directory contains entry points for the various tools that are included in the project. Currently these are the dsfx and dsfxctl tools. They each define Go main packages that can be compiled and distributed.

In general, code in this directory should be relevant to the starting, stopping, and running of the tools. It should not contain any business logic or other code that is not relevant to the tool itself. Rather, it should delegate to the code in the internal directory to do the actual work and serve as a thin bootstrapping layer.

docs

The docs directory contains documentation for the project. Files that are children of this folder are intended to be viewed by end users. Feel free to peruse around and learn about the system.

Files that are located in docs/internals are not intended for end users. They are intended for developers and contributors to the project. These files are intended to be used as a reference for understanding the codebase and how it works. The file you are reading right now is located in this folder.

internal

The internal directory contains the core code of the project. This code is not intended for public use and is meant for internal use only. The code in this directory is organized into several subdirectories, each of which serves a specific purpose.

internal/client

This section contains the client code, which is what a user or admin runs on their local machine to interact with their server (see internal/peer). The client code is responsible for sending and receiving messages to and from the server, as well as handling user input and output. Currently the code for the CLI is located in this package, but we would love to see that moved to the cmd folder as it is not applicable to the library side of the tool. The direct consumer of this package is the cmd/dsfxctl main package.

internal/lib

This section contains shared libraries that are used by the rest of the codebase. They aren't intended for public use, but can be used freely throughout the rest of the application. Code that lives in this section should pay close attention to unit tests and benchmarking, as it is likely used in more than on place, which means that changes here are force multipliers for both bugs and performance.

internal/peer

This section contains the peer code, which is what the server runs on the remote machine. The peer code is responsible for communicating with the client code, other peers, and the filesystem. The direct consumer of this package is the cmd/dsfx main package.

internal/sim

This section of the codebase contains various helpers for simulating different parts of the system. You can use these helpers to simulate latency, corruption, and other external factors inside of your unit tests.

Currently, these tools are most useful in tests as mock implementations of the system. They are not intended for production use. When we build out the simulation framework, these tools will mature and be targeted for that use case.

internal/tool

This section of the codebase contains various internal tools and scripts that are used for development, testing, and deployment purposes. These tools are not intended for public use and are meant for internal use only. Each one is a main package with an executable, usually with a single command. Some accept command line arguments, you will need to check the code for those. Alternatively, you may run the tool with -h to see the available options.

The tools in this directory can be loosely compared to a bin directory, or maybe a Makefile. We prioritize using Go for our tools, so we try to stay inside of the Go ecosystem as much as possible. We also try to keep the tools as simple as possible, so that they are easy to use and understand. It is much better to have a lot of really small, really focused tools than a few massive tools that do everything.