Merge pull request #1 from octodns/wip-poc

POC source for SPF management to sketch out the idea

CHANGELOG.md

@@ -1,11 +1,3 @@
-## TODO: v0.0.1 - 20??-??-?? - Moving
+## v0.0.1 - 2023-08-21 - Initial (Alpha) Release
 
-#### Nothworthy Changes
-
-* Initial extraction of SpfSource from octoDNS core
-
-TODO: anything else
-
-#### Stuff
-
-TODO: anything else
+It exists

README.md

@@ -1,8 +1,6 @@
-TODO: Review this README and add or modify as necessary.
+## SPF Value Management for octoDNS
 
-## SPF Value Management provider for octoDNS
-
-An [octoDNS](https://github.com/octodns/octodns/) provider that targets [SPF Value Management](https://github.com/octodns/octodns-spf).
+An [octoDNS](https://github.com/octodns/octodns/) provider that supports managing SPF values in TXT records.
 
 ### Installation
 
@@ -34,25 +32,98 @@ octodns-spf==0.0.1
 
 ### Configuration
 
+#### Options & Defaults
+
 ```yaml
 providers:
-  spf:
+  spf-google:
     class: octodns_spf.SpfSource
-    # TODO
+    # See https://datatracker.ietf.org/doc/html/rfc7208#section-5 for the
+    # details of the various mechinisms below. Each is an array of zero or more
+    # items to be added to the SPF record. Mechinisms are specified in the order
+    # the parameters are listed below and value order is preserved.
+    # (default: empty list)
+    a_records: []
+    mx_records: []
+    ip4_addresses: []
+    ip6_addresses: []
+    includes: []
+    exists: []
+    # The "all" value to be appended onto the SPF value, there's not a clear
+    # consensus on best practice here, but there does seem to be a slight leaning
+    # towards hard-failing, "-all". Soft-fail can be enabled by setting this
+    # value to `true`. If for some reason you donot want to specify a fail mode,
+    # this can be set to `null` and it will be ommited.
+    # See https://news.ycombinator.com/item?id=34344590 for some discussion
+    # (default: false, hard fail)
+    soft_fail: false
+    # Wether or not this provider will merge it's configuration with any
+    # prexisting SPF value in an APEX TXT record. If `false` an error will be
+    # thrown. If `true` the existing values, wether from a previous SpfSource or
+    # any other provider, will be preserved and this provider's config will be
+    # appended onto each mechinism.
+    merging_enabled: false
+    ttl: 3600
 ```
 
-### Support Information
+#### Read World Example
 
-#### Records
+A base that disables all email applied to all Zones
 
-TODO: All octoDNS record types are supported.
+```yaml
+providers:
+  spf-base:
+    class: octodns_spf.SpfSource
+```
 
-#### Dynamic
+A follow on source that will add Google Workspace's recommended config
 
-TODO: SpfSource does not support dynamic records.
+```yaml
+providers:
+  spf-mail:
+    class: octodns_spf.SpfSource
+    includes:
+      - _spf.google.com
+      - _spf.salesforce.com
+    soft_fail: true
+    merging_enabled: true
+```
+
+Per https://support.google.com/a/answer/10684623?hl=en and
+https://help.salesforce.com/s/articleView?id=000382664&type=1
+
+Zones would have one or more of these providers added to their sources list
+
+```yaml
+zones:
+  ...
+
+  # main zone that will be generally used for email
+  github.com.:
+    sources:
+      - config
+      - spf-base
+      - spf-mail
+    targets:
+      ...
+
+  # ancilary zone, pretty much everything else
+  githubusercontent.com.:
+    sources:
+      - config
+      - spf-base
+    targets:
+      ...
+
+  ...
+```
+
+### Support Information
+
+#### Records
+
+TXT
 
 ### Development
 
 See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.
-
-TODO: any provider specific setup, a docker compose to run things locally etc?