Skip to content

implementation-plan.md

Latest commit

 

History

History
139 lines (111 loc) · 6.83 KB

implementation-plan.md

File metadata and controls

139 lines (111 loc) · 6.83 KB
Raw

go-sdk-windowscsp — Implementation Plan

A Go SDK for Windows Configuration Service Providers (CSPs), generated from Microsoft's canonical DDF v2 (Device Description Framework) metadata.

The lifecycle is: collect → snapshot → generate → ship.

Microsoft DDF v2 zip ──fetchddf──▶ metadata/csp/*.json ──gencsp──▶ windowscsp/{csp,policy}/<area>/
   (download.microsoft.com)          (committed, reviewed)           (generated LCRUD packages)

Design sources

Concern Borrowed from
DDF acquisition, snapshots, provenance, update PR workflow go-bindings-wmi (cmd/fetchddf, internal/cspschema)
Client + per-domain service registry go-sdk-jamfpro-v2 (jamfpro.go, account_preferences)
Template-driven codegen, view/render firewall, file separation, regen CI gate go-bindings-win32 (internal/codegen, functions.tmpl, biometricframework)

Phase 0 — Scaffold

  • go.mod: github.com/deploymenttheory/go-sdk-windowscsp, Go 1.22.
  • Directory layout:
cmd/fetchddf/            acquisition CLI (download, verify, snapshot)
cmd/gencsp/              codegen CLI (offline, deterministic)
internal/ddf/            DDF v2 XML parser + snapshot model
internal/codegen/        naming / pipeline / view / build / render / fileasm / generator
metadata/csp/            committed JSON snapshots + PROVENANCE.json
windowscsp/              public SDK root (Client, registry)
windowscsp/client/       transport interface, Value, mock transport
windowscsp/syncml/       SyncML (OMA-DM) document builder + recorder transport
windowscsp/csp/<area>/     generated: standalone CSPs (~70)
windowscsp/policy/<area>/  generated: Policy areas (~240)

Phase 1 — DDF acquisition (internal/ddf, cmd/fetchddf)

  • Parser for DDF v2 XML (MgmtTree/Node/DFProperties + MSFT: extensions). AccessType/DFFormat are sets of empty child elements — captured with an xml:",any" + xml.Name catch-all. Dynamic nodes have an empty NodeName and carry MSFT:DynamicNodeNaming; the model keeps title (DFTitle), dynamicNaming, applicability, allowed values, deprecation, GP mapping.
  • cmd/fetchddf: downloads the pinned release (DDFv2Feb2026.zip, sha256 bf667d…ff14), verifies the digest, parses every .xml zip entry, writes one JSON snapshot per CSP to metadata/csp/ plus PROVENANCE.json, prunes stale snapshots. -zip for offline runs, -discover scrapes the Microsoft Learn DDF page for a newer drop URL.
  • Snapshots are committed; fetching a new release is a deliberate, reviewed act.

Phase 2 — Codegen engine (internal/codegen, cmd/gencsp)

Two-firewall architecture:

  1. build is the only stage that inspects the snapshot model. It flattens node trees into fully-resolved view models: URI constants/builders, LCRUD methods, enum constant blocks, service metadata.
  2. render turns view models into Go source only through embedded text/template files (templates/*.tmpl): doc.tmpl, service.tmpl, uris.tmpl, functions.tmpl, enums.tmpl, registry.tmpl.

fileasm is the single scaffold chokepoint: // Code generated by go-sdk-windowscsp-codegen. DO NOT EDIT. header, package clause, grouped imports, go/format.Source. The header doubles as the prune sentinel: generated files not rewritten in a run are deleted; hand-written files are never touched.

Determinism: sorted node walks, sorted package lists, deterministic collision suffixing, LF-normalized output (.gitattributes), gofmt.

LCRUD mapping (per DDF AccessType)

DDF access Generated method Notes
Get (leaf) Get<Node>(ctx) (T, error) T from DFFormat: int→int64, bool→bool, chr/date/time/xml→string, b64/bin→[]byte, float→float64
Get (interior with dynamic children) List<Node>(ctx) ([]string, error) OMA-DM Get on an interior node enumerates children
Add (leaf) Create<Node>(ctx, value T) error
Add (dynamic interior) Create<Node>(ctx, name string) error creates the container node
Replace Update<Node>(ctx, value T) error
Delete Delete<Node>(ctx[, name string]) error
Exec Exec<Node>(ctx[, value T]) error value omitted for null format

Dynamic path segments (empty NodeName) become string parameters, named from the node's DFTitle when present. Method doc comments carry the DDF description, default, applicability (min OS build, CSP version), and deprecation notices.

Phase 3 — Runtime client (windowscsp, windowscsp/client, windowscsp/syncml)

  • client.Client is the narrow transport interface all generated services depend on: Get, List, Add, Replace, Delete, Exec against OMA-URIs with a typed Value{Format, Data}.
  • client.MockClient: in-memory CSP tree for tests.
  • syncml: renders operations into OMA-DM SyncML fragments/documents (for MDM servers and Intune custom OMA-URI), plus a Recorder transport that queues writes and emits the batch document.
  • Root package windowscsp: NewClient(transport) *Client with generated CSP and Policy family registries (one field per generated domain), the jamfpro three-tier registry pattern.
  • A real device-side executor (MDM WMI bridge, root\cimv2\mdm\dmmap) can implement client.Client out-of-tree (e.g. from go-bindings-wmi).

Phase 4 — Full generation

  • Run fetchddf against the Feb 2026 drop → commit metadata/csp/.
  • Run gencsp → commit windowscsp/csp/, windowscsp/policy/, registries.
  • go build ./... must pass.

Phase 5 — Testing

  • internal/ddf: fixture DDF XML covering enums, dynamic nodes, applicability, deprecation → parsed-model assertions.
  • internal/codegen: golden-file tests (fixture snapshot → expected emitted files) + naming unit tests.
  • cmd/fetchddf: synthetic in-memory zip round-trip.
  • Generated-surface smoke tests against client.MockClient (Reboot CSP, one Policy area) — typed round-trips, URI correctness.
  • windowscsp/syncml: document rendering tests.
  • Determinism: regen-twice equality is enforced by the CI diff gate.

Phase 6 — CI pipelines (.github/workflows)

  • ci.yml
    • test: build, vet (non-generated), unit tests (ubuntu + windows).
    • regen: go run ./cmd/gencsp from committed snapshots, then git add -N windowscsp && git diff --exit-code — the determinism gate.
  • ddf-update.yml: weekly schedule + manual dispatch. Runs fetchddf -discover (finds new Microsoft drops), regenerates, and opens a PR via peter-evans/create-pull-request when metadata/ or generated code changed.
  • Existing template workflows (lint, release-please, dependabot) retained.

Non-goals (v1)

  • Executing CSP operations on-device (WMI/MDM bridge) — interface seam only.
  • SyncML client protocol (sessions, auth); only document construction.
  • DDF DependencyBehavior / CommonErrorResults modeling.