query DEP names (#128)

Author: jessepeterson

cmd/depserver/main.go

@@ -13,6 +13,7 @@ import (
 	"github.com/micromdm/nanodep/client"
 	dephttp "github.com/micromdm/nanodep/http"
 	"github.com/micromdm/nanodep/http/api"
+	"github.com/micromdm/nanodep/http/apinext"
 	"github.com/micromdm/nanodep/log/caller"
 	"github.com/micromdm/nanodep/log/slog"
 	"github.com/micromdm/nanodep/proxy"
@@ -102,6 +103,10 @@ func main() {
 	assignerMux.Handle("PUT", api.StoreAssignerProfileHandler(storage, logger.With("handler", "store-assigner-profile")))
 	handleStrippedAPI(assignerMux, endpointAssigner)
 
+	namesMux := dephttp.NewMethodMux()
+	namesMux.Handle("GET", apinext.NewQueryDEPNamesHandler(storage, logger.With("handler", "query-dep-names")))
+	handleStrippedAPI(namesMux, "/v1/dep_names")
+
 	handleStrippedAPI(api.NewBypassCodeHandler(), endpointALBC)
 
 	handleStrippedAPI(

docs/openapi.yaml

@@ -19,6 +19,52 @@ paths:
                   version:
                     type: string
                     example: "v0.1.0"
+  /v1/dep_names:
+    get:
+      description: Query DEP names.
+      parameters:
+        - in: query
+          name: dep_name
+          schema:
+            type: array
+            items:
+              type: string
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            example: 20
+            default: 100
+        - in: query
+          name: offset
+          schema:
+            type: integer
+        - in: query
+          name: cursor
+          schema:
+            type: string
+            example: afcadc29a704
+      security:
+        - basicAuth: []
+      responses:
+        '200':
+          description: Returns DEP name query results.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DEPNamesQueryResponse'
+        '400':
+          description: Problem with the provided API query parameters.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Server error querying DEP names.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /v1/assigner/{name}:
     get:
       description: Return the assigner profile UUID for the given DEP name.
@@ -391,6 +437,26 @@ components:
           format: url
           example: "http://127.0.0.1:8080/"
           description: The base URL of the Apple Device Assignment Services server to call out to. Typically only overridden when talking to another DEP server such as the `depsim` simulator.
+    DEPNamesQueryResponse:
+      type: object
+      properties:
+        dep_names:
+          type: array
+          items:
+            type: string
+        next_cursor:
+          description: For storage backends that support cursor-based pagination this will contain the next cursor value.
+          type: string
+    ErrorResponse:
+      type: object
+      description: Error response.
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Error string.
+          example: The sun is shining.
     OAuth1Tokens:
       type: object
       properties:

docs/operations-guide.md

@@ -133,6 +133,24 @@ A brief overview of the endpoints is provided here. For detailed API semantics p
 
 Returns a JSON response with the version of the running NanoDEP server.
 
+#### DEP name query
+
+* Endpoint: `GET /v1/dep_names`
+
+The `/v1/dep_names` endpoint queries and returns DEP names. The DEP names need to have an upstaged (uploaded) DEP PKI operation to be considered query-able. Optional parameters are any specific `dep_name` parameters. Depending on the storage backend `offset` and `limit` or `cursor` parameters may be provided. For example:
+
+`http://[::1]9001/v1/dep_names?dep_name=myMDMserver&dep_name=myMDMserver2&limit=2&offset=3`
+
+Should return something like (if only `myMDMServer2` was query-able):
+
+```json
+{
+  "dep_names": [
+    "myMDMserver2"
+  ]
+}
+```
+
 #### Token PKI
 
 * Endpoint: `GET, PUT /v1/tokenpki/{name}`

http/apinext/api.go

@@ -0,0 +1,54 @@
+// Package apinext implements HTTP handlers for the NanoDEP API.
+// It exists to break the circular dependency between the storage and api packages.
+package apinext
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/micromdm/nanolib/log"
+)
+
+// writeJSON encodes v to JSON writing to w using the HTTP status of header.
+// An error during encoding is logged to logger if it is not nil.
+// If header is 0 then none will be written to w (which defaults to 200).
+// Nothing will be encoded nor written to w if v is nil.
+func writeJSON(w http.ResponseWriter, v interface{}, header int, logger log.Logger) {
+	w.Header().Set("Content-type", "application/json")
+
+	if header > 0 {
+		w.WriteHeader(header)
+	}
+
+	if v == nil {
+		return
+	}
+
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "\t")
+	err := enc.Encode(v)
+	if err != nil && logger != nil {
+		logger.Info("msg", "encoding json", "err", err)
+	}
+}
+
+// logAndWriteJSONError logs msg and err to logger as well as writes err to w as JSON.
+// If header is 0 it will default to 500.
+func logAndWriteJSONError(logger log.Logger, w http.ResponseWriter, msg string, err error, header int) {
+	if logger != nil {
+		logger.Info("msg", msg, "err", err)
+	}
+
+	errStr := "<nil error>"
+	if err != nil {
+		errStr = err.Error()
+	}
+
+	out := &ErrorResponseJson{Error: errStr}
+
+	if header < 1 {
+		header = 500
+	}
+
+	writeJSON(w, out, header, logger)
+}

http/apinext/depnames.go

@@ -0,0 +1,70 @@
+package apinext
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+
+	"github.com/micromdm/nanodep/storage"
+
+	"github.com/micromdm/nanolib/log"
+	"github.com/micromdm/nanolib/log/ctxlog"
+)
+
+// NewQueryDEPNamesHandler returns a handler that queries DEP names.
+func NewQueryDEPNamesHandler(store storage.DEPNamesQuery, logger log.Logger) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		p := new(storage.Pagination)
+
+		logger := ctxlog.Logger(r.Context(), logger)
+
+		var err error
+		// extract and set pagination limit
+		if limitRaw := r.URL.Query().Get("limit"); limitRaw != "" {
+			limit, err := strconv.Atoi(limitRaw)
+			if err != nil {
+				logAndWriteJSONError(logger, w, "converting limit param", err, http.StatusBadRequest)
+				return
+			}
+
+			p.Limit = &limit
+		}
+
+		// extract and set pagination offset
+		if offsetRaw := r.URL.Query().Get("offset"); offsetRaw != "" {
+			offset, err := strconv.Atoi(offsetRaw)
+			if err != nil {
+				logAndWriteJSONError(logger, w, "converting offset param", err, http.StatusBadRequest)
+				return
+			}
+
+			p.Offset = &offset
+		}
+
+		// extract and set pagination cursor
+		if cursorRaw := r.URL.Query().Get("cursor"); cursorRaw != "" {
+			p.Cursor = &cursorRaw
+		}
+
+		// assemble the query request
+		q := &storage.DEPNamesQueryRequest{
+			Filter: &storage.DEPNamesQueryFilter{
+				DEPNames: r.URL.Query()["dep_name"],
+			},
+			Pagination: p,
+		}
+
+		// perform query
+		ret, err := store.QueryDEPNames(r.Context(), q)
+		if err != nil {
+			logAndWriteJSONError(logger, w, "querying DEP names", err, 0)
+			return
+		}
+
+		// log the success
+		logger.Debug("msg", fmt.Sprintf("queried DEP names: %d", len(ret.DEPNames)))
+
+		// output the return
+		writeJSON(w, ret, http.StatusOK, logger)
+	}
+}

http/apinext/generate.go

@@ -0,0 +1,5 @@
+package apinext
+
+//go:generate oa2js -o ErrorResponse.json ../../docs/openapi.yaml ErrorResponse
+//go:generate go-jsonschema -p $GOPACKAGE --tags json --only-models --output schema.go ErrorResponse.json
+//go:generate rm -f ErrorResponse.json

http/apinext/schema.go

@@ -0,0 +1,28 @@
+package storage
+
+import "context"
+
+// DEPNamesQueryFilter is the filter parameters for querying DEP names.
+type DEPNamesQueryFilter struct {
+	// DEPNames specifies which DEP names to query for.
+	// DEP names in this list which exists are returned.
+	DEPNames []string `json:"dep_names"`
+}
+
+// DEPNamesQueryRequest is the parameters for querying DEP names.
+type DEPNamesQueryRequest struct {
+	Filter     *DEPNamesQueryFilter `json:"filter,omitempty"`
+	Pagination *Pagination          `json:"pagination,omitempty"`
+}
+
+// DEPNamesQueryResult is the resulting paginated of the DEP names query.
+type DEPNamesQueryResult struct {
+	DEPNames []string `json:"dep_names"`
+
+	PaginationNextCursor
+}
+
+type DEPNamesQuery interface {
+	// QueryDEPNames queries and returns DEP names.
+	QueryDEPNames(ctx context.Context, req *DEPNamesQueryRequest) (*DEPNamesQueryResult, error)
+}

storage/depnames.go

@@ -235,3 +235,8 @@ func (s *FileStorage) retrieveTokenPKIExtn(name, extn string) ([]byte, []byte, e
 	}
 	return certBytes, keyBytes, err
 }
+
+// QueryDEPNames queries and returns DEP names.
+func (s *FileStorage) QueryDEPNames(ctx context.Context, req *storage.DEPNamesQueryRequest) (*storage.DEPNamesQueryResult, error) {
+	return nil, errors.New("not implemented")
+}