Skip to content

Latest commit

 

History

History
80 lines (61 loc) · 4.93 KB

CONTRIBUTE.md

File metadata and controls

80 lines (61 loc) · 4.93 KB
Raw

Contribute

We welcome contributions to this project. Please read the following guidelines.

Guidelines

We follow the "fork-and-pull" Git workflow. Here are the steps:

  1. Fork the repo on GitHub.
  2. Clone the project to your own machine.
  3. Commit changes to your own branch.
  4. Push your work back up to your fork.
  5. Submit a Pull Request so we can review your changes.

Setting up the project

  • Clone the repository.
  • Install Android Studio (if you haven't already).
  • Open the project in Android Studio.
  • Ensure the project builds without errors (dependencies should download automatically).
  • You can now use the Android emulator or a physical device to run the app.

Architecture Overview

Below is an overview of the architecture of the Android app to help you understand the codebase better.

Background Workers

The application leverages Android's WorkManager API to manage periodic tasks necessary for its operation. There are two primary background workers that are initially started right after enrollment: FleetCheckinWorker and ElasticWorker. These workers are responsible for interacting with Fleet and Elasticsearch to ensure that the device is compliant with the current policy and that data is being sent to the server.

FleetCheckinWorker

Purpose

The FleetCheckinWorker is tasked with periodic check-ins with the Fleet server. These check-ins are crucial for:

  • Receiving new policy updates which might include changes in data collection frequency, data types collected (internally "paths"), or security parameters (api keys, certificates).
  • Updating the local policy data with any new configurations received from the Fleet server (Fleet Checkin -> PolicyData).
  • Confirming the device's compliance with the current policies (Fleet Ack).
Implementation Details
  • Trigger: This worker runs at intervals specified by the checkin_interval field in the policy.
  • Data Handling: During each run, it fetches the current enrollment details from the EnrollmentData database to authenticate and establish a connection with the Fleet server. The necessary details include the server URL and certificates for a secure connection.
  • Execution: On execution, it sends a check-in request and waits for a response. Upon receiving a new policy, it updates the local database with the new settings and reschedules itself if the checkin_interval has changed. Also it Acknowledges possible policy changes to the Fleet server.

ElasticWorker

Purpose

The ElasticWorker handles the aggregation and transmission of logged data to an Elasticsearch server. Its responsibilities include:

  • Collecting data entries from various components within the app which may include logs, metrics, or operational events (modular data collection).
  • Ensuring that the data is formatted correctly, batched, and sent to the Elasticsearch server at regular intervals.
Implementation Details
  • Trigger: Operates at intervals defined by the put_interval in the policy.
  • Data Collection: Utilizes the ComponentFactory to access individual component buffers, each potentially holding data of type ElasticDocument which represent the documents for Elasticsearch.
  • Data Processing: Before transmission, it combines data entries into larger batches to minimize network requests and align with Elasticsearch's bulk upload API.

The WorkScheduler class manages the scheduling and re-scheduling of these workers based on the current policy settings.

Note: It is not possible to use periodic tasks with intervals less than 15 minutes on Android 12 and above, which is why this app uses "worker chaining" to achieve the desired behavior.

Class Structure

The app classes are organized into several functional areas:

  • FleetEnrollmentX: Manages the enrollment process to fleet.
  • FleetCheckinX: Manages the check-in process to fleet.
  • AppX: Handles general app functionality (e.g., database, converters).
  • ComponentNameX: Manages components that fetch various data from the device and send these data to an internal buffer (which is then emptied by the ElasticWorker mentioned above).

Within each functional area, the classes are further organized into the following categories:

  • XActivity: UI classes displaying data to the user.
  • XRepository: Classes handling business logic, typically linked to an Activity.
  • XRequest/XResponse: Retrofit classes for API call requests and responses.
  • XWorker: Background task handlers (see above).
  • XComp: Implementations of the Component interface.
  • XData: Classes defining the Room database structure for local data storage.

Developing a New Component

To develop a new component:

  1. Implement the Component interface.
  2. Extend the ElasticDocument class to represent the data your component will send to Elasticsearch.
  3. Add your component to the ComponentFactory class to ensure it is used by ElasticWorker.