refact: loading

* loading:
  * feature: added JSONDoc() and JSONMatcher() for symetry with YAMLDoc(). Will allow to deprecate
    [github.com/go-openapi/loads.JSONDoc]
  * tests: refactored using embedded fixture

  * added support for plain fs.FS file systems, not just fs.ReadFileFS
  * fixed bug in local file loading strategy: using embed.FS on windows
    should not use '\' for paths. For convenience, strip invalid leading '/' or
    '.' from embed.FS paths. Basically, local embed FS on windows
    behaves like on unix.

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

loading/fixtures/petstore_fixture.json

@@ -0,0 +1 @@
+{"swagger":"2.0","info":{"version":"1.0.0","title":"Swagger Petstore","description":"A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification","termsOfService":"http://helloreverb.com/terms/","contact":{"name":"Swagger API team","email":"foo@example.com","url":"http://swagger.io"},"license":{"name":"MIT","url":"http://opensource.org/licenses/MIT"}},"host":"petstore.swagger.wordnik.com","basePath":"/api","schemes":["http"],"consumes":["application/json"],"produces":["application/json"],"paths":{"/pets":{"get":{"description":"Returns all pets from the system that the user has access to","operationId":"findPets","produces":["application/json","application/xml","text/xml","text/html"],"parameters":[{"name":"tags","in":"query","description":"tags to filter by","required":false,"type":"array","items":{"type":"string"},"collectionFormat":"csv"},{"name":"limit","in":"query","description":"maximum number of results to return","required":false,"type":"integer","format":"int32"}],"responses":{"200":{"description":"pet response","schema":{"type":"array","items":{"$ref":"#/definitions/pet"}}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/errorModel"}}}},"post":{"description":"Creates a new pet in the store.  Duplicates are allowed","operationId":"addPet","produces":["application/json"],"parameters":[{"name":"pet","in":"body","description":"Pet to add to the store","required":true,"schema":{"$ref":"#/definitions/newPet"}}],"responses":{"200":{"description":"pet response","schema":{"$ref":"#/definitions/pet"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/errorModel"}}}}},"/pets/{id}":{"get":{"description":"Returns a user based on a single ID, if the user does not have access to the pet","operationId":"findPetById","produces":["application/json","application/xml","text/xml","text/html"],"parameters":[{"name":"id","in":"path","description":"ID of pet to fetch","required":true,"type":"integer","format":"int64"}],"responses":{"200":{"description":"pet response","schema":{"$ref":"#/definitions/pet"}},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/errorModel"}}}},"delete":{"description":"deletes a single pet based on the ID supplied","operationId":"deletePet","parameters":[{"name":"id","in":"path","description":"ID of pet to delete","required":true,"type":"integer","format":"int64"}],"responses":{"204":{"description":"pet deleted"},"default":{"description":"unexpected error","schema":{"$ref":"#/definitions/errorModel"}}}}}},"definitions":{"pet":{"required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}}},"newPet":{"allOf":[{"$ref":"#/definitions/pet"},{"required":["name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}]},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}

loading/petstore_fixture.yaml renamed to loading/fixtures/petstore_fixture.yaml

@@ -0,0 +1,22 @@
+package loading
+
+import (
+	"encoding/json"
+	"errors"
+	"path/filepath"
+)
+
+// JSONMatcher matches json for a file loader.
+func JSONMatcher(path string) bool {
+	ext := filepath.Ext(path)
+	return ext == ".json" || ext == ".jsn" || ext == ".jso"
+}
+
+// JSONDoc loads a json document from either a file or a remote url.
+func JSONDoc(path string, opts ...Option) (json.RawMessage, error) {
+	data, err := LoadFromFileOrHTTP(path, opts...)
+	if err != nil {
+		return nil, errors.Join(err, ErrLoader)
+	}
+	return json.RawMessage(data), nil
+}

loading/json.go

@@ -0,0 +1,43 @@
+package loading
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestJSONMatcher(t *testing.T) {
+	t.Run("should recognize a json file", func(t *testing.T) {
+		assert.True(t, JSONMatcher("local.json"))
+		assert.True(t, JSONMatcher("local.jso"))
+		assert.True(t, JSONMatcher("local.jsn"))
+		assert.False(t, JSONMatcher("local.yml"))
+	})
+}
+
+func TestJSONDoc(t *testing.T) {
+	t.Run("should retrieve pet store API as JSON", func(t *testing.T) {
+		serv := httptest.NewServer(http.HandlerFunc(serveJSONPestore))
+
+		defer serv.Close()
+
+		s, err := JSONDoc(serv.URL)
+		require.NoError(t, err)
+		require.NotNil(t, s)
+		require.JSONEq(t, string(jsonPetStore), string(s))
+	})
+
+	t.Run("should not retrieve any doc", func(t *testing.T) {
+		ts := httptest.NewServer(http.HandlerFunc(func(rw http.ResponseWriter, _ *http.Request) {
+			rw.WriteHeader(http.StatusNotFound)
+			_, _ = rw.Write([]byte("\n"))
+		}))
+		defer ts.Close()
+
+		_, err := JSONDoc(ts.URL)
+		require.Error(t, err)
+	})
+}

loading/json_test.go

@@ -16,6 +16,7 @@ package loading
 
 import (
 	"context"
+	"embed"
 	"fmt"
 	"io"
 	"log"
@@ -63,30 +64,32 @@ func LoadFromFileOrHTTP(pth string, opts ...Option) ([]byte, error) {
 // - `file://host/folder/file` becomes an UNC path like `\\host\folder\file` (no port specification is supported)
 // - `file:///c:/folder/file` becomes `C:\folder\file`
 // - `file://c:/folder/file` is tolerated (without leading `/`) and becomes `c:\folder\file`
-func LoadStrategy(pth string, local, remote func(string) ([]byte, error), _ ...Option) func(string) ([]byte, error) {
+func LoadStrategy(pth string, local, remote func(string) ([]byte, error), opts ...Option) func(string) ([]byte, error) {
 	if strings.HasPrefix(pth, "http") {
 		return remote
 	}
+	o := optionsWithDefaults(opts)
+	_, isEmbedFS := o.fs.(embed.FS)
 
 	return func(p string) ([]byte, error) {
 		upth, err := url.PathUnescape(p)
 		if err != nil {
 			return nil, err
 		}
 
-		if !strings.HasPrefix(p, `file://`) {
+		cpth, hasPrefix := strings.CutPrefix(upth, "file://")
+		if !hasPrefix || isEmbedFS || runtime.GOOS != "windows" {
+			// crude processing: trim the file:// prefix. This leaves full URIs with a host with a (mostly) unexpected result
 			// regular file path provided: just normalize slashes
-			return local(filepath.FromSlash(upth))
-		}
-
-		if runtime.GOOS != "windows" {
-			// crude processing: this leaves full URIs with a host with a (mostly) unexpected result
-			upth = strings.TrimPrefix(upth, `file://`)
+			if isEmbedFS {
+				// on windows, we need to slash the path if FS is an embed FS.
+				return local(strings.TrimLeft(filepath.ToSlash(cpth), "./")) // remove invalid leading characters for embed FS
+			}
 
-			return local(filepath.FromSlash(upth))
+			return local(filepath.FromSlash(cpth))
 		}
 
-		// windows-only pre-processing of file://... URIs
+		// windows-only pre-processing of file://... URIs, excluding embed.FS
 
 		// support for canonical file URIs on windows.
 		u, err := url.Parse(filepath.ToSlash(upth))

loading/loading.go

@@ -16,11 +16,14 @@ package loading
 
 import (
 	"context"
+	"io/fs"
 	"net/http"
 	"net/http/httptest"
 	"os"
+	"path/filepath"
 	"runtime"
 	"testing"
+	"testing/fstest"
 	"time"
 
 	"github.com/stretchr/testify/assert"
@@ -35,7 +38,7 @@ func TestLoadFromHTTP(t *testing.T) {
 		content, err := LoadFromFileOrHTTP(ts.URL)
 		require.NoError(t, err)
 
-		assert.YAMLEq(t, string(YAMLPetStore), string(content))
+		assert.YAMLEq(t, string(yamlPetStore), string(content))
 	})
 
 	t.Run("should not load from invalid URL", func(t *testing.T) {
@@ -116,9 +119,10 @@ func TestLoadFromHTTP(t *testing.T) {
 
 			t.Run("with custom HTTP client mocking a remote", func(t *testing.T) {
 				cwd, _ := os.Getwd()
+				fixtureDir := filepath.Join(cwd, "fixtures")
 				client := &http.Client{
 					// intercepts calls to the server and serves local files instead
-					Transport: http.NewFileTransport(http.FS(os.DirFS(cwd))),
+					Transport: http.NewFileTransport(http.Dir(fixtureDir)),
 				}
 
 				t.Run("should not load unknown path", func(t *testing.T) {
@@ -169,19 +173,43 @@ func TestLoadFromHTTP(t *testing.T) {
 		})
 	})
 
-	t.Run("should load from local embedded file system", func(t *testing.T) {
+	t.Run("should load from local embedded file system (single file)", func(t *testing.T) {
+		// using plain fs.FS
+		rooted, err := fs.Sub(embeddedFixtures, "fixtures")
+		require.NoError(t, err)
 		b, err := LoadFromFileOrHTTP("petstore_fixture.yaml",
+			WithFS(rooted),
+		)
+		require.NoError(t, err)
+		assert.YAMLEq(t, string(yamlPetStore), string(b))
+	})
+
+	t.Run("should load from memory file system (single file)", func(t *testing.T) {
+		mapfs := make(fstest.MapFS)
+		mapfs["file"] = &fstest.MapFile{Data: []byte("content"), Mode: fs.ModePerm}
+		// using fs.ReadFileFS
+		b, err := LoadFromFileOrHTTP("file",
+			WithFS(mapfs),
+		)
+		require.NoError(t, err)
+		assert.Equal(t, string("content"), string(b))
+	})
+
+	t.Run("should load from local embedded file system (path)", func(t *testing.T) {
+		// using plain fs.ReadFileFS
+		// NOTE: this doesn't work on windows, because embed.FS uses / even on windows
+		b, err := LoadFromFileOrHTTP("fixtures/petstore_fixture.yaml",
 			WithFS(embeddedFixtures),
 		)
 		require.NoError(t, err)
-		assert.YAMLEq(t, string(YAMLPetStore), string(b))
+		assert.YAMLEq(t, string(yamlPetStore), string(b))
 	})
 }
 
 func TestLoadStrategy(t *testing.T) {
 	const thisIsNotIt = "not it"
 	loader := func(_ string) ([]byte, error) {
-		return YAMLPetStore, nil
+		return yamlPetStore, nil
 	}
 	remLoader := func(_ string) ([]byte, error) {
 		return []byte(thisIsNotIt), nil
@@ -190,7 +218,7 @@ func TestLoadStrategy(t *testing.T) {
 	t.Run("should serve local strategy", func(t *testing.T) {
 		ldr := LoadStrategy("blah", loader, remLoader)
 		b, _ := ldr("")
-		assert.YAMLEq(t, string(YAMLPetStore), string(b))
+		assert.YAMLEq(t, string(yamlPetStore), string(b))
 	})
 
 	t.Run("should serve remote strategy with http", func(t *testing.T) {

loading/loading_test.go

@@ -90,17 +90,33 @@ func WithHTTPClient(client *http.Client) Option {
 	}
 }
 
-// WithFS sets a file system for the local file loader.
+// WithFileFS sets a file system for the local file loader.
+//
+// If the provided file system is a [fs.ReadFileFS], the ReadFile function is used.
+// Otherwise, ReadFile is wrapped using [fs.ReadFile].
 //
 // By default, the file system is the one provided by the os package.
 //
 // For example, this may be set to consume from an embedded file system, or a rooted FS.
-func WithFS(fs fs.ReadFileFS) Option {
+func WithFS(filesystem fs.FS) Option {
 	return func(o *options) {
-		o.fs = fs
+		if rfs, ok := filesystem.(fs.ReadFileFS); ok {
+			o.fs = rfs
+
+			return
+		}
+		o.fs = readFileFS{FS: filesystem}
 	}
 }
 
+type readFileFS struct {
+	fs.FS
+}
+
+func (r readFileFS) ReadFile(name string) ([]byte, error) {
+	return fs.ReadFile(r.FS, name)
+}
+
 func optionsWithDefaults(opts []Option) options {
 	const defaultTimeout = 30 * time.Second
 

loading/options.go

@@ -18,31 +18,39 @@ import (
 	"embed"
 	"fmt"
 	"net/http"
+	"os"
+	"path"
+	"testing"
 )
 
 // embedded test files
 
-//go:embed petstore_fixture.yaml
+//go:embed fixtures/*
 var embeddedFixtures embed.FS
 
-// YAMLPetStore embeds the classical pet store API swagger example.
-var YAMLPetStore []byte
+// yamlPetStore embeds the classical pet store API swagger example.
+var yamlPetStore []byte
+var jsonPetStore []byte
 
-func init() {
-	data, err := embeddedFixtures.ReadFile("petstore_fixture.yaml")
-	if err != nil {
-		panic(fmt.Errorf("wrong embedded FS configuration: %w", err))
-	}
+func TestMain(m *testing.M) {
+	yamlPetStore = mustLoadFixture("petstore_fixture.yaml")
+	jsonPetStore = mustLoadFixture("petstore_fixture.json")
 
-	YAMLPetStore = data
+	os.Exit(m.Run())
 }
 
 // test handlers
 
 // serveYAMLPestore is a http handler to serve the YAMLPestore doc.
 func serveYAMLPestore(rw http.ResponseWriter, _ *http.Request) {
 	rw.WriteHeader(http.StatusOK)
-	_, _ = rw.Write(YAMLPetStore)
+	_, _ = rw.Write(yamlPetStore)
+}
+
+// serveJSONPestore is a http handler to serve the jsonPestore doc.
+func serveJSONPestore(rw http.ResponseWriter, _ *http.Request) {
+	rw.WriteHeader(http.StatusOK)
+	_, _ = rw.Write(jsonPetStore)
 }
 
 func serveOK(rw http.ResponseWriter, _ *http.Request) {
@@ -86,3 +94,13 @@ func serveRequireHeaderFunc(key, value string) func(http.ResponseWriter, *http.R
 		rw.WriteHeader(http.StatusForbidden)
 	}
 }
+
+func mustLoadFixture(name string) []byte {
+	const msg = "wrong embedded FS configuration: %w"
+	data, err := embeddedFixtures.ReadFile(path.Join("fixtures", name))
+	if err != nil {
+		panic(fmt.Errorf(msg, err))
+	}
+
+	return data
+}

loading/serve_test.go

@@ -34,12 +34,7 @@ func YAMLDoc(path string, opts ...Option) (json.RawMessage, error) {
 		return nil, err
 	}
 
-	data, err := yamlutils.YAMLToJSON(yamlDoc)
-	if err != nil {
-		return nil, err
-	}
-
-	return data, nil
+	return yamlutils.YAMLToJSON(yamlDoc)
 }
 
 // YAMLData loads a yaml document from either http or a file.