[ENC-921] Add Config API's to public contract (#11)

This commit adds the new `encore.dev/config` API's
to the `encore.dev` module.

It also adds new comments explaining to users why
we panic in this code, and provides a link to go to
the current implementation of the given function.

beta/auth/auth.go

@@ -23,5 +23,11 @@ type UID string
 // API calls made with these options will not be made and will immediately return
 // a client-side error.
 func WithContext(ctx context.Context, uid UID, data interface{}) context.Context {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/auth/auth.go#L53-L57
  panic("encore apps must be run using the encore command")
 }

beta/auth/pkgfn.go

@@ -4,6 +4,12 @@ package auth
 // The second result is true if there is a user and false
 // if the request was made without authentication details.
 func UserID() (UID, bool) {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/auth/pkgfn.go#L11-L13
  panic("encore apps must be run using the encore command")
 }
 
@@ -16,5 +22,11 @@ func UserID() (UID, bool) {
 // usr, ok := auth.Data().(*user.Data)
 // if !ok { /* ... */ }
 func Data() any {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/auth/pkgfn.go#L24-L26
  panic("encore apps must be run using the encore command")
 }

beta/errs/builder.go

@@ -9,35 +9,80 @@ type Builder struct {
 }
 
 // B is a shorthand for creating a new Builder.
-func B() *Builder { panic("encore apps must be run using the encore command") }
+func B() *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ //
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L25-L25
+ panic("encore apps must be run using the encore command")
+}
 
 // Code sets the error code.
 func (*Builder) Code(c ErrCode) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L28-L32
  panic("encore apps must be run using the encore command")
 }
 
 // Msg sets the error message.
 func (*Builder) Msg(msg string) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L35-L38
  panic("encore apps must be run using the encore command")
 }
 
 // Msgf is like Msg but uses fmt.Sprintf to construct the message.
 func (*Builder) Msgf(format string, args ...interface{}) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L41-L44
  panic("encore apps must be run using the encore command")
 }
 
 // Meta appends metadata key-value pairs.
 func (*Builder) Meta(metaPairs ...interface{}) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L47-L50
  panic("encore apps must be run using the encore command")
 }
 
 // Details sets the details.
 func (*Builder) Details(det ErrDetails) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L53-L57
  panic("encore apps must be run using the encore command")
 }
 
 // Cause sets the underlying error cause.
 func (*Builder) Cause(err error) *Builder {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L60-L71
  panic("encore apps must be run using the encore command")
 }
 
@@ -50,5 +95,11 @@ func (*Builder) Cause(err error) *Builder {
 // If Msg has not been set and Cause is nil,
 // the Msg is set to "unknown error".
 func (*Builder) Err() error {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/builder.go#L81-L109
  panic("encore apps must be run using the encore command")
 }

beta/errs/error.go

@@ -44,54 +44,108 @@ type Metadata map[string]interface{}
 // If err is already an *Error its code, message, and details
 // are copied over to the new error.
 func Wrap(err error, msg string, metaPairs ...interface{}) error {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L66-L82
  panic("encore apps must be run using the encore command")
 }
 
 // WrapCode is like Wrap but also sets the error code.
 // If code is OK it reports nil.
 func WrapCode(err error, code ErrCode, msg string, metaPairs ...interface{}) error {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L86-L102
  panic("encore apps must be run using the encore command")
 }
 
 // Convert converts an error to an *Error.
 // If the error is already an *Error it returns it unmodified.
 // If err is nil it returns nil.
 func Convert(err error) error {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L107-L118
  panic("encore apps must be run using the encore command")
 }
 
 // Code reports the error code from an error.
 // If err is nil it reports OK.
 // Otherwise if err is not an *Error it reports Unknown.
 func Code(err error) ErrCode {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L123-L130
  panic("encore apps must be run using the encore command")
 }
 
 // Meta reports the metadata included in the error.
 // If err is nil or the error lacks metadata it reports nil.
 func Meta(err error) Metadata {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L134-L139
  panic("encore apps must be run using the encore command")
 }
 
 // Details reports the error details included in the error.
 // If err is nil or the error lacks details it reports nil.
 func Details(err error) ErrDetails {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L143-L148
  panic("encore apps must be run using the encore command")
 }
 
 // Error reports the error code and message.
 func (*Error) Error() string {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L151-L153
  panic("encore apps must be run using the encore command")
 }
 
 // ErrorMessage reports the error message, joining this
 // error's message with the messages from any underlying errors.
 func (*Error) ErrorMessage() string {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L157-L181
  panic("encore apps must be run using the encore command")
 }
 
 // Unwrap returns the underlying error, if any.
 func (*Error) Unwrap() error {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L184-L186
  panic("encore apps must be run using the encore command")
 }
 
@@ -102,5 +156,11 @@ func (*Error) Unwrap() error {
 //
 // {"code": "ok", "message": "", "details": null}
 func HTTPError(w http.ResponseWriter, err error) {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/beta/errs/error.go#L193-L195
  panic("encore apps must be run using the encore command")
 }

config/pkgfn.go

@@ -0,0 +1,28 @@
+// Package config provides a simple way to access configuration values for a
+// service using the Load function.
+//
+// # By default configuration is pulled at build time from CUE files in each service directory
+//
+// For more information about configuration see https://encore.dev/docs/develop/config.
+package config
+
+// Load returns the fully loaded configuration for this service.
+//
+// The configuration is loaded from the CUE files in the service directory and
+// will be validated by Encore at compile time, which ensures this function will
+// return a valid configuration at runtime.
+//
+// Encore will generate a `encore.gen.cue` file in the service directory which
+// will contain generated CUE matching the configuration type T.
+//
+// Note: This function can only be called from within services and cannot be
+// referenced from other services.
+func Load[T any]() T {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/config/pkgfn.go#L25-L41
+ panic("encore apps must be run using the encore command")
+}

config/types.go

@@ -0,0 +1,42 @@
+package config
+
+import (
+ "time"
+
+ "encore.dev/types/uuid"
+)
+
+// Value represents a value in the configuration for this application
+// which can be any value represented in the configuration files.
+//
+// It is a function because the underlying value could change while
+// the application is still running due to unit tests providing
+// overrides to test different behaviours. To change the value within
+// a single unit test, use the et.SetCfg function.
+type Value[T any] func() T
+
+// Values represents a list of values in the configuration for this
+// application which can be any value represented in the configuration files.
+//
+// It is a function because the underlying value could change while
+// the application is still running due to unit tests providing
+// overrides to test different behaviours.
+type Values[T any] func() []T
+
+type Bool = Value[bool]
+type Int8 = Value[int8]
+type Int16 = Value[int16]
+type Int32 = Value[int32]
+type Int64 = Value[int64]
+type Uint8 = Value[uint8]
+type Uint16 = Value[uint16]
+type Uint32 = Value[uint32]
+type Uint64 = Value[uint64]
+type Float32 = Value[float32]
+type Float64 = Value[float64]
+type String = Value[string]
+type Bytes = Value[[]byte]
+type Time = Value[time.Time]
+type UUID = Value[uuid.UUID]
+type Int = Value[int]
+type Uint = Value[uint]

cron/cron.go

@@ -37,6 +37,12 @@ package cron
 // return nil
 // }
 func NewJob(id string, jobConfig JobConfig) *Job {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/cron/cron.go#L39-L47
  panic("encore apps must be run using the encore command")
 }
 

et/config.go

@@ -0,0 +1,19 @@
+package et
+
+import (
+ "encore.dev/config"
+)
+
+// SetCfg changes the value of cfg to newValue within the current test and any subtests.
+// Other tests running will not be affected.
+//
+// It does not support setting slices and panics if given a config value that is a slice.
+func SetCfg[T any](cfg config.Value[T], newValue T) {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/et/config.go#L13-L23
+ panic("encore apps must be run using the encore command")
+}

et/pubsub.go

@@ -6,6 +6,12 @@ import (
 
 // Topic returns a TopicHelper for the given topic.
 func Topic[T any](topic *pubsub.Topic[T]) TopicHelpers[T] {
+ // Encore will provide an implementation to this function at runtime, we do not expose
+ // the implementation in the API contract as it is an implementation detail, which may change
+ // between releases.
+ //
+ // The current implementation of this function can be found here:
+ // https://github.com/encoredev/encore/blob/v1.9.0/runtime/et/pubsub.go#L8-L10
  panic("encore apps must be run using the encore command")
 }