run

README

Run

Package Run provides useful, yet opinionated integrations for workloads running on Cloud Run. It loosely follows the general development tips from the official documentation.

Cloud Run Services

HTTP Services

Read more in run-examples.

package main

import (
 "context"
 "fmt"
 "net/http"

 "cloud.google.com/go/bigquery"
 "github.com/helloworlddan/run"
)

func main() {
 http.HandleFunc("/", indexHandler)

 // Store config
 run.PutConfig("some-key", "some-val")

 // Store client with lazy initialization
 var bqClient *bigquery.Client
 run.LazyClient("bigquery", func() {
  run.Debug(nil, "lazy init: bigquery")
  var err error
  ctx := context.Background()
  bqClient, err = bigquery.NewClient(ctx, run.ProjectID())
  if err != nil {
   run.Error(nil, err)
  }
  run.Client("bigquery", bqClient)
 })

 // Define shutdown behavior and serve HTTP
 err := run.ServeHTTP(func(ctx context.Context) {
  run.Debug(nil, "shutting down connections...")
  if bqClient != nil { // Maybe nil due to lazy loading
   bqClient.Close()
  }
  run.Debug(nil, "connections closed")
 }, nil)
 if err != nil {
  run.Fatal(nil, err)
 }
}

func indexHandler(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "Name: %s\n", run.ServiceName())
 fmt.Fprintf(w, "Revision: %s\n", run.ServiceRevision())
 fmt.Fprintf(w, "ProjectID: %s\n", run.ProjectID())

 // Access config
 cfg, err := run.GetConfig("some-key")
 if err != nil {
  run.Error(r, err)
 }

 // Access client
 var client *bigquery.Client
 client, err = run.UseClient("bigquery", client)
 if err != nil {
  run.Error(nil, err)
 }
 // NOTE: use client
 _ = client

 fmt.Fprintf(w, "Config[some-key]: %s\n", cfg)
 run.Debugf(r, "request completed")
}

GRPC Services

Read more in run-examples.

package main

import (
 "context"
 "time"

 "github.com/helloworlddan/run"
 "github.com/helloworlddan/run-examples/run-grpc-service/runclock"
 "google.golang.org/grpc"
)

func main() {
 server := grpc.NewServer()
 runclock.RegisterRunClockServer(server, clockServer{})

 err := run.ServeGRPC(func(ctx context.Context) {
  run.Debug(nil, "shutting down connections...")
  time.Sleep(time.Second * 1) // Pretending to clean up
  run.Debug(nil, "connections closed")
 }, server)
 if err != nil {
  run.Fatal(nil, err)
 }
}

type clockServer struct {
 runclock.UnimplementedRunClockServer
}

func (srv clockServer) GetTime(ctx context.Context, in *runclock.Empty) (*runclock.Time, error) {
 now := time.Now()
 run.Debug(nil, "received request")
 return &runclock.Time{
  Formatted: now.GoString(),
 }, nil
}

A client implementation can be found here.

Cloud Run Jobs

Read more in run-examples.

package main

import (
 "context"
 "net/http"

 "cloud.google.com/go/bigquery"
 "github.com/helloworlddan/run"
)

func main() {
 // Store config
 run.PutConfig("my.app.key", "some value")
 cfgVal, err := run.GetConfig("my.app.key")
 if err != nil {
  run.Debugf(nil, "unable to read config: %v", err)
 }
 run.Infof(nil, "loaded config: %s", cfgVal)

 // Store client
 ctx := context.Background()
 bqClient, err := bigquery.NewClient(ctx, run.ProjectID())
 if err != nil {
  run.Error(nil, err)
 }
 run.Client("bigquery", bqClient)
 defer bqClient.Close()

 // Later usage
 var bqClient2 *bigquery.Client
 bqClient2, err = run.UseClient("bigquery", bqClient2)
 if err != nil {
  run.Error(nil, err)
 }

 _ = bqClient2

 // Make service account authenticated requests
 req, err := http.NewRequest(http.MethodGet, "https://google.com", nil)
 if err != nil {
  run.Error(nil, err)
 }
 req = run.AddOAuth2Header(req)
 resp, err := http.DefaultClient.Do(req)
 if err != nil {
  run.Error(nil, err)
 }
 defer resp.Body.Close()
 // read response
}

Documentation

Overview

Package Run provides useful, yet opinionated integrations for workloads running on Cloud Run.

Index

• func AddOAuth2Header(r *http.Request) *http.Request
• func AddOIDCHeader(r *http.Request, audience string) *http.Request
• func Alert(r *http.Request, message string)
• func Alertf(r *http.Request, format string, v ...any)
• func Client(name string, client any)
• func CountClients() int
• func CountConfig() int
• func Critical(r *http.Request, message string)
• func Criticalf(r *http.Request, format string, v ...any)
• func Debug(r *http.Request, message string)
• func Debugf(r *http.Request, format string, v ...any)
• func Default(r *http.Request, message string)
• func Defaultf(r *http.Request, format string, v ...any)
• func Emergency(r *http.Request, message string)
• func Emergencyf(r *http.Request, format string, v ...any)
• func Error(r *http.Request, err error)
• func Fatal(r *http.Request, err error)
• func GetConfig(key string) (string, error)
• func ID() string
• func Info(r *http.Request, message string)
• func Infof(r *http.Request, format string, v ...any)
• func JobExecution() string
• func JobName() string
• func JobTaskAttempt() int
• func JobTaskCount() int
• func JobTaskIndex() int
• func KNativeService() (knative.Service, error)
• func LazyClient(name string, init func())
• func ListClientNames() []string
• func ListConfigKeys() []string
• func LoadAllConfig()
• func LoadConfig(env string) (string, error)
• func Log(r *http.Request, severity string, message string)
• func Logf(r *http.Request, severity string, format string, v ...any)
• func Name() string
• func Notice(r *http.Request, message string)
• func Noticef(r *http.Request, format string, v ...any)
• func ProjectID() string
• func ProjectNumber() string
• func PutConfig(key string, val string)
• func Region() string
• func ResetClients()
• func ResetConfig()
• func ResetInstance()
• func ServeGRPC(shutdown func(context.Context), server *grpc.Server) error
• func ServeHTTP(shutdown func(context.Context), server *http.Server) error
• func ServiceAccountAccessToken() string
• func ServiceAccountEmail() string
• func ServiceAccountIdentityToken(audience string) string
• func ServiceName() string
• func ServicePort() string
• func ServiceRevision() string
• func URL() string
• func UseClient[T any](name string, client T) (T, error)
• func Warning(r *http.Request, message string)
• func Warningf(r *http.Request, format string, v ...any)
• type LogEntry
  • func (le LogEntry) String() string
• type SourceLocation

Functions

func AddOAuth2Header

func AddOAuth2Header(r *http.Request) *http.Request

AddOAuth2Header injects an `Authorization` header with a valid access token for the configured service account into the supplied HTTP request and returns it.

func AddOIDCHeader

func AddOIDCHeader(r *http.Request, audience string) *http.Request

AddOIDCHeader injects an `Authorization` header with a valid identity token for the configured service account into the supplied HTTP request and returns it.

func Alert

func Alert(r *http.Request, message string)

Alert logs a message with ALERT severity

func Alertf

func Alertf(r *http.Request, format string, v ...any)

Alertf logs a message with ALERT severity and message interpolation/formatting

func Client

func Client(name string, client any)

Client registers an already initialized client.

func CountClients

func CountClients() int

CountClients returns number of stored clients.

func CountConfig

func CountConfig() int

CountConfig returns number of stored config elements.

func Critical

func Critical(r *http.Request, message string)

Critical logs a message with CRITICAL severity

func Criticalf

func Criticalf(r *http.Request, format string, v ...any)

Criticalf logs a message with CRITICAL severity and message interpolation/formatting

func Debug

func Debug(r *http.Request, message string)

Debug logs a message with DEBUG severity

func Debugf

func Debugf(r *http.Request, format string, v ...any)

Debugf logs a message with DEBUG severity and message interpolation/formatting

func Default

func Default(r *http.Request, message string)

Default logs a message with DEFAULT severity

func Defaultf

func Defaultf(r *http.Request, format string, v ...any)

Defaultf logs a message with DEFAULT severity and message interpolation/formatting

func Emergency

func Emergency(r *http.Request, message string)

Emergency logs a message with EMERGENCY severity

func Emergencyf

func Emergencyf(r *http.Request, format string, v ...any)

Emergencyf logs a message with EMERGENCY severity and message interpolation/formatting

func Error

func Error(r *http.Request, err error)

Error logs a message with ERROR severity

func Fatal

func Fatal(r *http.Request, err error)

Fatal logs a message and terminates the process.

func GetConfig

func GetConfig(key string) (string, error)

GetConfig retrieves a value for a key from the global config store.

func ID

func ID() string

ID returns the unique instance ID of the Cloud Run instance serving the running job or service by referring to the metadata server.

If the current process does not seem to be hosted on Cloud Run, it will simply return `000000`.

func Info

func Info(r *http.Request, message string)

Info logs a message with INFO severity

func Infof

func Infof(r *http.Request, format string, v ...any)

Infof logs a message with INFO severity and message interpolation/formatting

func JobExecution

func JobExecution() string

JobExecution returns the execution identifier of the currently running Cloud Run job by looking up the `CLOUD_RUN_EXECUTION` environment variable.

func JobName

func JobName() string

JobName returns the name of the currently running Cloud Run job by looking up the `CLOUD_RUN_JOB` environment variable.

If the current process does not seem to be hosted on Cloud Run, it will simply return `local`.

func JobTaskAttempt

func JobTaskAttempt() int

JobTaskAttempt looks up and returns the current task attempt for the running Cloud Run job.

If the current process does not seem to be hosted on Cloud Run, it will sumply return `-1`.

func JobTaskCount

func JobTaskCount() int

JobTaskCount looks up and returns the current task count for the running Cloud Run job.

If the current process does not seem to be hosted on Cloud Run, it will sumply return `-1`.

func JobTaskIndex

func JobTaskIndex() int

JobTaskIndex looks up and returns the current task index for the running Cloud Run job.

If the current process does not seem to be hosted on Cloud Run, it will sumply return `-1`.

func KNativeService

func KNativeService() (knative.Service, error)

KNativeService loads and returns a KNative Serving representation of the current service. Requires at least roles/run.Viewer on itself.

func LazyClient

func LazyClient(name string, init func())

LazyClient registers an uninitialized client name with an initialization function. The init func should call Client() with the initialized client.

func ListClientNames

func ListClientNames() []string

ListClientNames returns a list of all available keys store in the global clients store.

func ListConfigKeys

func ListConfigKeys() []string

ListConfigKeys returns a list of all currently available keys in the global config store.

func LoadAllConfig

func LoadAllConfig()

LoadAllConfig loads all available environment variables and puts it in the config store.

func LoadConfig

func LoadConfig(env string) (string, error)

LoadConfig lookups the named environment variable, puts it's value into the global config store and returns the value.

func Log

func Log(r *http.Request, severity string, message string)

Log logs a message

func Logf

func Logf(r *http.Request, severity string, format string, v ...any)

Logf logs a message with message interpolation/formatting

func Name

func Name() string

Name returns a preferred name for the currently running Cloud Run service or job. This will be either the service or job name or simply 'local'.

func Notice

func Notice(r *http.Request, message string)

Notice logs a message with NOTICE severity

func Noticef

func Noticef(r *http.Request, format string, v ...any)

Noticef logs a message with NOTICE severity and message interpolation/formatting

func ProjectID

func ProjectID() string

ProjectID attempts to resolve the alphanumeric Google Cloud project ID that is hosting the current Cloud Run instance.

It loosely does so by looking up the following established precedence: - The environment variable `GOOGLE_CLOUD_PROJECT` - Querying the metadata server - Simply returning `local`

func ProjectNumber

func ProjectNumber() string

ProjectNumber looks up the numeric project number of the current Google Cloud project hosting the Cloud Run instance.

If the current process does not seem to be hosted on Cloud Run, it will return `000000000000`.

func PutConfig

func PutConfig(key string, val string)

PutConfig adds a K/V pair to the global config store.

func Region

func Region() string

Region looks up the actively serving region for this Cloud Run service.

If the current process does not seem to be hosted on Cloud Run, it will return `local`.

func ResetClients

func ResetClients()

ResetClients deletes all previously configured clients.

func ResetConfig

func ResetConfig()

ResetConfig deletes all previously configured config.

func ResetInstance

func ResetInstance()

ResetInstance resets the cached metadata of this instance

func ServeGRPC

func ServeGRPC(shutdown func(context.Context), server *grpc.Server) error

ServeGRPC starts the GRPC server, listens and serves requests

It also traps SIGINT and SIGTERM. Both signals will cause a graceful shutdown of the GRPC server and executes the user supplied shutdown func.

func ServeHTTP

func ServeHTTP(shutdown func(context.Context), server *http.Server) error

ServeHTTP starts the HTTP server, listens and serves requests

It also traps SIGINT and SIGTERM. Both signals will cause a graceful shutdown of the HTTP server and executes the user supplied shutdown func.

func ServiceAccountAccessToken

func ServiceAccountAccessToken() string

ServiceAccountAccessToken looks up and returns a fresh OAuth2 access token for the service account configured for this Cloud Run instance.

If the current process does not seem to be hosted on Cloud Run, it will return `local-access-token`.

func ServiceAccountEmail

func ServiceAccountEmail() string

ServiceAccountEmail looks up and returns the email of the service account configured for this Cloud Run instance.

If the current process does not seem to be hosted on Cloud Run, it will return `local@localhost.com`.

func ServiceAccountIdentityToken

func ServiceAccountIdentityToken(audience string) string

ServiceAccountIdentityToken attempts to mint an OIDC Identity Token for the specified `audience` using the metadata server.

If the current process does not seem to be hosted on Cloud Run, it will return `local-identity-token`.

func ServiceName

func ServiceName() string

ServiceName returns the name of the currently running Cloud Run service by looking up the `K_SERVICE` environment variable.

If the current process does not seem to be hosted on Cloud Run, it will simply return `local`.

func ServicePort

func ServicePort() string

ServicePort looks up and returns the configured service `$PORT` for this Cloud Run service.

If the current process does not seem to be hosted on Cloud Run, it will return the default value `8080`.

func ServiceRevision

func ServiceRevision() string

ServiceRevision returns the revision identifier of the currently running Cloud Run service by looking up the `K_REVISION` environment variable.

If the current process does not seem to be hosted on Cloud Run, it will return a deterministic identifier in the form of `<SERVICE_NAME>-00001-xxx`.

func URL

func URL() string

URL infers the URL with which this service will be addressable. This will either be 'http://localhost:8080' or the deterministic URL provided by Cloud Run

func UseClient

func UseClient[T any](name string, client T) (T, error)

UseClient is intended to retrieve a pointer to a client for a given key name. It requires the name of a stored client and a nil pointer of it's type. NOTE: maybe this shouldn't return T, just error...

func Warning

func Warning(r *http.Request, message string)

Warning logs a message with WARNING severity

func Warningf

func Warningf(r *http.Request, format string, v ...any)

Warningf logs a message with WARNING severity and message interpolation/formatting

Types

type LogEntry

type LogEntry struct {
	Message  string `json:"message"`
	Severity string `json:"severity,omitempty"`
	// Trace is the trace ID of the log message which will be propagated into
	// Cloud Trace.
	Trace string `json:"logging.googleapis.com/trace,omitempty"`
	// SourceLocation holds the location within the source where the log message
	// was generated.
	SourceLocation *SourceLocation `json:"logging.googleapis.com/sourceLocation,omitempty"`
	// Component is the name of the service or job that produces the log entry.
	Component string `json:"component,omitempty"`
}

LogEntry is the structured version of a single log entry intended to be stored in Google Cloud Logging in JSON-serialized form.

func (LogEntry) String

func (le LogEntry) String() string

String returns a JSON representation of the log entry.

type SourceLocation

type SourceLocation struct {
	File     string `json:"file,omitempty"`
	Function string `json:"function,omitempty"`
	Line     string `json:"line,omitempty"`
}

SourceLocation is the structured version of a location in the source code (at compile time) which emits a log entry (at runtime). It is intended to be embedded in a run.LogEntry in JSON-serialized form.