fixes to docs

README.md

@@ -2,26 +2,26 @@ WireNix is a Nix Flake designed to make creation of Wireguard mesh networks
 easier. The simplist and most likely layout is a full mesh network, but Wirenix
 can also support arbitrary graph topologies.  
 # Reading the README
-Due to Nix's dynamic typing, I have opted to define all my ACL configurations
+Due to Nix's dynamic typing, I have opted to define configurations in
-in psuedo-typescript to make options more legible. I have chosen typescript
+psuedo-typescript to make options more legible. I have chosen typescript
 because it looks somewhat like JSON and is easy to understand. Examples will
-still be given in Nix EL. Function signatures will still follow the traditional
+still be given in Nix EL.  
-Haskell-like function signatures seen throughout nix projects.  
 
-You can start by reading the [ACL Configuration](ACL Configuration) section,
+You can start by reading the [[ACL Configuration]] section, then reading
-then reading [Quick Start](Quick Start) section for how to configure your
+[[Quick Start]] section for how to configure your machines. Other sections
-machines. Other sections exist to provide helpful context and advanced usage,
+exist to provide helpful context and advanced usage, but should not be
-but should not be necessary for a working setup.  
+necessary for a working setup.  
 
 Wirenix assumes a flakes setup, that's what I use. Maybe it works without
 flakes, maybe not. I'm not familiar enough with the non-flakes landscape
 to provide support. I am open to making simple changes to make using this
-project without flakes easier if anyone has suggestions or wants to submit
+project work without flakes if anyone has suggestions or wants to submit
 a patch.  
 
 # ACL Configuration
 The ACL is a nix attrset designed to be represented in JSON for easy importing
-and potential use outside of the nix ecosystem.  
+and potential use outside of the nix ecosystem. The vast majority of all your
+wirenix configuration will end up in here, with a few exceptions noted later.  
 
 ## top level acl:
 ```typescript
@@ -31,7 +31,7 @@ type ACL = {
   groups: group[];
   peers: peer[];
   connections: connection[];
-  extraArgs?: any; // goes to intermediate config
+  extraArgs?: attrset; // goes to intermediate config
 };
 ```
 
@@ -46,7 +46,8 @@ make your own integrations.
 type subnet = {
   name: str;
   endpoints?: endpoint[];
-  extraArgs?: any; // goes to intermediate config subnet
+  presharedKeyFile?: str;
+  extraArgs?: attrset; // goes to intermediate config subnet
 };
 ```
 
@@ -55,7 +56,7 @@ type subnet = {
 type group = {
   name: str;
   endpoints?: endpoint[];
-  extraArgs?: any; // goes to intermediate config group
+  extraArgs?: attrset; // goes to intermediate config group
 };
 ```
 
@@ -66,19 +67,19 @@ type peer = {
   subnets: [subnetName: str]: {
     listenPort: int;
     ipAddresses?: str[];
-    extraArgs?: any; // goes to intermediate config subnetConnection
+    extraArgs?: attrset; // goes to intermediate config subnetConnection
   };
   publicKey: str;
   privateKeyFile: str; 
   groups?: str[];
   endpoints?: endpoint[];
-  extraArgs?: any; // goes to intermediate config peer
+  extraArgs?: attrset; // goes to intermediate config peer
 };
 ```
 
-`[subnetName: str]: {...}` means `subnets` is an object (attrset) with
+"`[subnetName: str]: {...}`" means "`subnets`" is an attrset with
-string typed keys, and values that follows the typing of the nested object
+string typed keys, and values that follow the typing of the nested object
-`...`.  
+"`...`".  
 
 ## Connection:
 ```typescript
@@ -86,7 +87,7 @@ type connection = {
   a: filter;
   b: filter;
   subnets: str[];
-  extraArgs?: any; // merged into intermediate config peerConnection
+  extraArgs?: attrset; // merged into intermediate config peerConnection
 };
 ```
 
@@ -106,7 +107,7 @@ type endpoint = {
   persistentKeepalive?: int;
   dynamicEndpointRefreshSeconds?: int;
   dynamicEndpointRefreshRestartSeconds?: int;
-  extraArgs?: any; // merged to intermediate config peerConnection.endpoin
+  extraArgs?: attrset; // merged to intermediate config peerConnection.endpoin
 };
 ```
 
@@ -187,10 +188,11 @@ wirenix = {
 # Architecture
 WireNix consists of 5 main components:  
 1. The shared ACL Configuration  
-2. The Key Providers  
+2. Parser Modules  
-3. Parser Modules  
+3. The intermediate Configuration  
-4. The intermediate Configuration  
+4. Configuration Modules
-5. Configuration Modules  
+5. The Key Providers  
+  
 
 The goal of splitting WireNix into modules is both for my own sanity when
 developing, and to make it hackable without requiring users to make their own
@@ -204,12 +206,10 @@ essentially rewriting this flake however you see fit, all without making a fork
 scratch).  
 
 ## ACL
-The shared ACL configuration should describe the full network topology. It does
+The shared ACL configuration describes the full network topology. It does not
-not need to consist only of NixOS peers (although at the moment, other peers
+need to consist only of NixOS peers The details of this file are documented in
-will have to be configured manually to conform to the expected settings). The
+the  [[Top Level ACL]] section. You can make your own ACL configuration format so
-details of this file are documented in the  `Top Level ACL` section.
+long as you keep the "`version`" field and set it to some unique name.
-You can make your own ACL configuration format so long as you keep the
-`version` field and set it to some unique name.
 
 ## Parser Modules
 Parser Modules are responsible for taking an ACL and converting it to the
@@ -241,16 +241,15 @@ version = "myParser";
 
 ## Intermediate Configuration
 The Intermediate Configuration is a recursive attrset that is more suited for
-being used in a NixOS configuration than the ACL Configuration.  
+being used in a NixOS configuration than the ACL Configuration. Unlike the ACL,
-Unlike the ACL, the intermediate configuration is more verbose, easier to
+the intermediate configuration is more verbose, easier to traverse, contains
-traverse, repeats itself often, and is recursive. This allows cross version
+duplicate information, and is recursive. This allows cross version
 compatibility so long as the intermediate configuration doesn't change. Any
 changes will likely only be the addition of optional features that do not
 interfere with existing intermediate configuration use, though at this stage
 there are no guarentees.   
-It can be assumed that all types mentioned are types for the intermediate
+Take note while reading that certain structures may be similar to the ACL,
-connection and NOT the related to types in the ACL. The intermediate
+but they are not necessarily the same as their ACL counterparts.  
-configuration has the following structure:  
 
 ### Root Structure
 ```typescript
@@ -258,6 +257,7 @@ type intermediateConfiguration = {
     peers: {[peerName: str]: peer};
     subnets: {[subnetName: str]: subnet};
     groups: {[groupName: str]: group};
+    extraArgs?: attrset;
 }
 ```
 
@@ -266,10 +266,10 @@ type intermediateConfiguration = {
 ```typescript
 type peer = {
     subnetConnections: {[subnetName: str]: subnetConnection};
-    groups: {[groupName: str]: group}
     publicKey: str;
     privateKeyFile: str; 
-    extraArgs?: any;
+    groups?: {[groupName: str]: group}    
+    extraArgs?: attrset;
 };
 ```
 
@@ -279,7 +279,8 @@ type peer = {
 ```typescript
 type subnet = {
     peers: {[peerName: str]: peer};
-    extraArgs?: any;
+    presharedKeyFile?: str;
+    extraArgs?: attrset;
 };
 ```
 
@@ -288,30 +289,30 @@ type subnet = {
 ```typescript
 type group = {
     peers: {[peerName: str]: peer};
-    extraArgs?: any;
+    extraArgs?: attrset;
 };
 ```
 
-### Peer Connection
+### Subnet Connection
 
 ```typescript
-type peerConnection = {
+type subnetConnection = {
-    peer: peer;
+    subnet: subnet;
     ipAddresses: str[];
-    endpoint: endpoint;
+    listenPort: int;
-    extraArgs?: any;
+    peerConnections: {[peerName: str]: peerConnection};
+    extraArgs?: attrset;
 };
 ```
 
-### Subnet Connection
+### Peer Connection
 
 ```typescript
-type subnetConnection = {
+type peerConnection = {
-    subnet: subnet;
+    peer: peer;
     ipAddresses: str[];
-    listenPort: int;
+    endpoint: endpoint;
-    peerConnections: {[peerName: str]: peerConnection};
+    extraArgs?: attrset;
-    extraArgs?: any;
 };
 ```
 
@@ -324,14 +325,10 @@ type endpoint = {
    persistentKeepalive?: int;
    dynamicEndpointRefreshSeconds?: int;
    dynamicEndpointRefreshRestartSeconds?: int;
-   extraArgs?: any;
+   extraArgs?: attrset;
 };
 ```
 
-Unlike the ACL, this structure is recursive, resembling an arbitrary graph.
-This graph can be traversed back and forth in circles until you run out of
-stack space.  
-
 ## Configuration Modules
 Configuration Modules take the Key provider list and Intermediate Configuration
 to produce NixOS configurations. By default, there exist configuration modules
@@ -381,7 +378,7 @@ wirenix.keyProviders = ["myKeyProvider"];
 # Integrations:
 By default, WireNix supports setting wireguard keypairs with
 [agenix-rekey](https://github.com/oddlama/agenix-rekey).
-WireNix also supports networkd, network manager, and the nixos static network
+WireNix also supports using either networkd or the nixos static network
 configuration (default).  
 
 Using networkd: