v0.13.0 Introducing the Rolodex.

.github/workflows/build.yaml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Go 1.x
         uses: actions/setup-go@v3
         with:
-          go-version: 1.19
+          go-version: 1.21
         id: go
 
       - name: Checkout code

datamodel/document_config.go

@@ -4,8 +4,11 @@
 package datamodel
 
 import (
-	"net/http"
+	"github.com/pb33f/libopenapi/utils"
+	"io/fs"
+	"log/slog"
 	"net/url"
+	"os"
 )
 
 // DocumentConfiguration is used to configure the document creation process. It was added in v0.6.0 to allow
@@ -20,17 +23,47 @@ type DocumentConfiguration struct {
 
 	// RemoteURLHandler is a function that will be used to retrieve remote documents. If not set, the default
 	// remote document getter will be used.
+	//
+	// The remote handler is only used if the BaseURL is set. If the BaseURL is not set, then the remote handler
+	// will not be used, as there will be nothing to use it against.
+	//
 	// Resolves [#132]: https://github.com/pb33f/libopenapi/issues/132
-	RemoteURLHandler func(url string) (*http.Response, error)
+	RemoteURLHandler utils.RemoteURLHandler
 
 	// If resolving locally, the BasePath will be the root from which relative references will be resolved from.
 	// It's usually the location of the root specification.
+	//
+	// Be warned, setting this value will instruct the rolodex to index EVERY yaml and JSON file it finds from the
+	// base path. The rolodex will recurse into every directory and pick up everything form this location down.
+	//
+	// To avoid sucking in all the files, set the FileFilter to a list of specific files to be included.
 	BasePath string // set the Base Path for resolving relative references if the spec is exploded.
 
+	// FileFilter is a list of specific files to be included by the rolodex when looking up references. If this value
+	// is set, then only these specific files will be included. If this value is not set, then all files will be included.
+	FileFilter []string
+
+	// RemoteFS is a filesystem that will be used to retrieve remote documents. If not set, then the rolodex will
+	// use its own internal remote filesystem implementation. The RemoteURLHandler will be used to retrieve remote
+	// documents if it has been set. The default is to use the internal remote filesystem loader.
+	RemoteFS fs.FS
+
+	// LocalFS is a filesystem that will be used to retrieve local documents. If not set, then the rolodex will
+	// use its own internal local filesystem implementation. The default is to use the internal local filesystem loader.
+	LocalFS fs.FS
+
 	// AllowFileReferences will allow the index to locate relative file references. This is disabled by default.
+	//
+	// Deprecated: This behavior is now driven by the inclusion of a BasePath. If a BasePath is set, then the
+	// rolodex will look for relative file references. If no BasePath is set, then the rolodex will not look for
+	// relative file references. This value has no effect as of version 0.13.0 and will be removed in a future release.
 	AllowFileReferences bool
 
 	// AllowRemoteReferences will allow the index to lookup remote references. This is disabled by default.
+	//
+	// Deprecated: This behavior is now driven by the inclusion of a BaseURL. If a BaseURL is set, then the
+	// rolodex will look for remote references. If no BaseURL is set, then the rolodex will not look for
+	// remote references. This value has no effect as of version 0.13.0 and will be removed in a future release.
 	AllowRemoteReferences bool
 
 	// AvoidIndexBuild will avoid building the index. This is disabled by default, only use if you are sure you don't need it.
@@ -52,18 +85,21 @@ type DocumentConfiguration struct {
 	// So if libopenapi is returning circular references for this use case, then this option should be enabled.
 	// this is disabled by default, which means array circular references will be checked.
 	IgnoreArrayCircularReferences bool
-}
 
-func NewOpenDocumentConfiguration() *DocumentConfiguration {
-	return &DocumentConfiguration{
-		AllowFileReferences:   true,
-		AllowRemoteReferences: true,
-	}
+	// SkipCircularReferenceCheck will skip over checking for circular references. This is disabled by default, which
+	// means circular references will be checked. This is useful for developers building out models that should be
+	// indexed later on.
+	SkipCircularReferenceCheck bool
+
+	// Logger is a structured logger that will be used for logging errors and warnings. If not set, a default logger
+	// will be used, set to the Error level.
+	Logger *slog.Logger
 }
 
-func NewClosedDocumentConfiguration() *DocumentConfiguration {
+func NewDocumentConfiguration() *DocumentConfiguration {
 	return &DocumentConfiguration{
-		AllowFileReferences:   false,
-		AllowRemoteReferences: false,
+		Logger: slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+			Level: slog.LevelError,
+		})),
 	}
 }

datamodel/document_config_test.go

@@ -9,13 +9,6 @@ import (
 )
 
 func TestNewClosedDocumentConfiguration(t *testing.T) {
-	cfg := NewClosedDocumentConfiguration()
-	assert.False(t, cfg.AllowRemoteReferences)
-	assert.False(t, cfg.AllowFileReferences)
-}
-
-func TestNewOpenDocumentConfiguration(t *testing.T) {
-	cfg := NewOpenDocumentConfiguration()
-	assert.True(t, cfg.AllowRemoteReferences)
-	assert.True(t, cfg.AllowFileReferences)
+	cfg := NewDocumentConfiguration()
+	assert.NotNil(t, cfg)
 }

datamodel/high/base/contact_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"fmt"
 	lowmodel "github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
@@ -70,7 +71,7 @@ email: [email protected]
 	// build low
 	var lowContact lowbase.Contact
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowContact)
-	_ = lowContact.Build(nil, cNode.Content[0], nil)
+	_ = lowContact.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	// build high
 	highContact := NewContact(&lowContact)

datamodel/high/base/dynamic_value_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
 	"github.com/pb33f/libopenapi/index"
@@ -116,7 +117,7 @@ func TestDynamicValue_MarshalYAMLInline(t *testing.T) {
 	_ = yaml.Unmarshal([]byte(ymlSchema), &node)
 
 	lowProxy := new(lowbase.SchemaProxy)
-	err := lowProxy.Build(nil, node.Content[0], idx)
+	err := lowProxy.Build(context.Background(), nil, node.Content[0], idx)
 	assert.NoError(t, err)
 
 	lowRef := low.NodeReference[*lowbase.SchemaProxy]{
@@ -160,7 +161,7 @@ func TestDynamicValue_MarshalYAMLInline_Error(t *testing.T) {
 	_ = yaml.Unmarshal([]byte(ymlSchema), &node)
 
 	lowProxy := new(lowbase.SchemaProxy)
-	err := lowProxy.Build(nil, node.Content[0], idx)
+	err := lowProxy.Build(context.Background(), nil, node.Content[0], idx)
 	assert.NoError(t, err)
 
 	lowRef := low.NodeReference[*lowbase.SchemaProxy]{

datamodel/high/base/example_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"fmt"
 	lowmodel "github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
@@ -29,7 +30,7 @@ x-hack: code`
 	var lowExample lowbase.Example
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowExample)
 
-	_ = lowExample.Build(&cNode, cNode.Content[0], nil)
+	_ = lowExample.Build(context.Background(), &cNode, cNode.Content[0], nil)
 
 	// build high
 	highExample := NewExample(&lowExample)
@@ -59,7 +60,7 @@ func TestExtractExamples(t *testing.T) {
 	var lowExample lowbase.Example
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowExample)
 
-	_ = lowExample.Build(nil, cNode.Content[0], nil)
+	_ = lowExample.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	examplesMap := make(map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*lowbase.Example])
 	examplesMap[lowmodel.KeyReference[string]{
@@ -89,7 +90,7 @@ x-hack: code`
 	_ = lowmodel.BuildModel(node.Content[0], &lowExample)
 
 	// build out low-level example
-	_ = lowExample.Build(nil, node.Content[0], nil)
+	_ = lowExample.Build(context.Background(), nil, node.Content[0], nil)
 
 	// create a new high-level example
 	highExample := NewExample(&lowExample)

datamodel/high/base/external_doc_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"fmt"
 	lowmodel "github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
@@ -26,7 +27,7 @@ x-hack: code`
 	var lowExt lowbase.ExternalDoc
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowExt)
 
-	_ = lowExt.Build(nil, cNode.Content[0], nil)
+	_ = lowExt.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	highExt := NewExternalDoc(&lowExt)
 
@@ -61,7 +62,7 @@ x-hack: code`
 	_ = lowmodel.BuildModel(node.Content[0], &lowExt)
 
 	// build out low-level properties (like extensions)
-	_ = lowExt.Build(nil, node.Content[0], nil)
+	_ = lowExt.Build(context.Background(), nil, node.Content[0], nil)
 
 	// create new high-level ExternalDoc
 	highExt := NewExternalDoc(&lowExt)

datamodel/high/base/info_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"fmt"
 	"testing"
 
@@ -32,7 +33,7 @@ x-cli-name: chicken cli`
 
 	var lowInfo lowbase.Info
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowInfo)
-	_ = lowInfo.Build(nil, cNode.Content[0], nil)
+	_ = lowInfo.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	highInfo := NewInfo(&lowInfo)
 
@@ -74,7 +75,7 @@ version: 1.2.3`
 	// build out the low-level model
 	var lowInfo lowbase.Info
 	_ = lowmodel.BuildModel(&node, &lowInfo)
-	_ = lowInfo.Build(nil, node.Content[0], nil)
+	_ = lowInfo.Build(context.Background(), nil, node.Content[0], nil)
 
 	// build the high level model
 	highInfo := NewInfo(&lowInfo)
@@ -97,7 +98,7 @@ url: https://opensource.org/licenses/MIT`
 	// build out the low-level model
 	var lowLicense lowbase.License
 	_ = lowmodel.BuildModel(node.Content[0], &lowLicense)
-	_ = lowLicense.Build(nil, node.Content[0], nil)
+	_ = lowLicense.Build(context.Background(), nil, node.Content[0], nil)
 
 	// build the high level model
 	highLicense := NewLicense(&lowLicense)
@@ -140,7 +141,7 @@ func TestInfo_Render(t *testing.T) {
 	// build low
 	var lowInfo lowbase.Info
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowInfo)
-	_ = lowInfo.Build(nil, cNode.Content[0], nil)
+	_ = lowInfo.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	// build high
 	highInfo := NewInfo(&lowInfo)
@@ -181,7 +182,7 @@ x-cake:
 	// build low
 	var lowInfo lowbase.Info
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowInfo)
-	_ = lowInfo.Build(nil, cNode.Content[0], nil)
+	_ = lowInfo.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	// build high
 	highInfo := NewInfo(&lowInfo)

datamodel/high/base/licence_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	lowmodel "github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
 	"github.com/stretchr/testify/assert"
@@ -44,7 +45,7 @@ url: https://pb33f.io/not-real
 	// build low
 	var lowLicense lowbase.License
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowLicense)
-	_ = lowLicense.Build(nil, cNode.Content[0], nil)
+	_ = lowLicense.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	// build high
 	highLicense := NewLicense(&lowLicense)
@@ -92,7 +93,7 @@ func TestLicense_Render_IdentifierAndURL_Error(t *testing.T) {
 	// build low
 	var lowLicense lowbase.License
 	_ = lowmodel.BuildModel(cNode.Content[0], &lowLicense)
-	err := lowLicense.Build(nil, cNode.Content[0], nil)
+	err := lowLicense.Build(context.Background(), nil, cNode.Content[0], nil)
 
 	assert.Error(t, err)
 }

datamodel/high/base/schema.go

@@ -302,7 +302,6 @@ func NewSchema(schema *base.Schema) *Schema {
 		s.Anchor = schema.Anchor.Value
 	}
 
-	// TODO: check this behavior.
 	for i := range schema.Enum.Value {
 		enum = append(enum, schema.Enum.Value[i].Value)
 	}

datamodel/high/base/schema_proxy_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"github.com/pb33f/libopenapi/datamodel/low"
 	lowbase "github.com/pb33f/libopenapi/datamodel/low/base"
 	"github.com/pb33f/libopenapi/index"
@@ -40,7 +41,7 @@ func TestSchemaProxy_MarshalYAML(t *testing.T) {
 	_ = yaml.Unmarshal([]byte(ymlSchema), &node)
 
 	lowProxy := new(lowbase.SchemaProxy)
-	err := lowProxy.Build(nil, node.Content[0], idx)
+	err := lowProxy.Build(context.Background(), nil, node.Content[0], idx)
 	assert.NoError(t, err)
 
 	lowRef := low.NodeReference[*lowbase.SchemaProxy]{