README
¶
Go FDK Documentation
This is documentation for the Go function development kit (FDK) which provides convenience functions for writing Go Fn code.
For getting started using the Go FDK , see the tutorial here.
To get the Go FDK simply import it in your program github.com/fnproject/fdk-go, and use go get to get it.
User Information
- See the Fn Quickstart for sample commands.
- Detailed installation instructions.
- Configure your CLI Context.
- For a list of commands see Fn CLI Command Guide and Reference.
- For general information see Fn docs and tutorials.
Go FDK Development
See CONTRIBUTING for information on contributing to the project.
Documentation
¶
Overview ¶
Example ¶
/*
* Copyright (c) 2019, 2020 Oracle and/or its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package main
import (
"context"
"encoding/json"
"io"
"net/http"
fdk "github.com/fnproject/fdk-go"
)
func main() {
fdk.Handle(fdk.HandlerFunc(myHandler))
}
func main() { println("use main()") }
// TODO make http.Handler example
func myHandler(ctx context.Context, in io.Reader, out io.Writer) {
fnctx, ok := fdk.GetContext(ctx).(fdk.HTTPContext)
if !ok {
// optionally, this may be a good idea
fdk.WriteStatus(out, 400)
fdk.SetHeader(out, "Content-Type", "application/json")
io.WriteString(out, `{"error":"function not invoked via http trigger"}`)
return
}
contentType := fnctx.Header().Get("Content-Type")
if contentType != "application/json" {
// can assert content type for your api this way
fdk.WriteStatus(out, 400)
fdk.SetHeader(out, "Content-Type", "application/json")
io.WriteString(out, `{"error":"invalid content type"}`)
return
}
if fnctx.RequestMethod() != "PUT" {
// can assert certain request methods for certain endpoints
fdk.WriteStatus(out, 404)
fdk.SetHeader(out, "Content-Type", "application/json")
io.WriteString(out, `{"error":"route not found, method not supported"}`)
return
}
var person struct {
Name string `json:"name"`
}
json.NewDecoder(in).Decode(&person)
// this is where you might insert person into a database or do something else
all := struct {
Name string `json:"name"`
URL string `json:"url"`
Header http.Header `json:"header"`
Config map[string]string `json:"config"`
}{
Name: person.Name,
URL: fnctx.RequestURL(),
Header: fnctx.Header(),
Config: fnctx.Config(),
}
// you can write your own headers & status, if you'd like to
fdk.SetHeader(out, "Content-Type", "application/json")
fdk.WriteStatus(out, 201)
json.NewEncoder(out).Encode(&all)
}
Output:
Index ¶
- Constants
- func AddHeader(out io.Writer, key, value string)
- func Handle(handler Handler)
- func HandleContext(ctx context.Context, handler Handler)
- func SetHeader(out io.Writer, key, value string)
- func WithContext(ctx context.Context, fnctx Context) context.Context
- func WriteStatus(out io.Writer, status int)
- type Context
- type HTTPContext
- type Handler
- type HandlerFunc
- type TracingContext
Examples ¶
Constants ¶
const Version = "0.0.52"
Version is the FDK version
Variables ¶
This section is empty.
Functions ¶
func Handle ¶
func Handle(handler Handler)
Handle will run the event loop for a function. Handle should be invoked through main() in a user's function and can handle communication between the function and fn server via any of the supported formats.
func HandleContext ¶
HandleContext works the same as Handle, but takes a context that will exit the handler loop when canceled/timed out.
func WithContext ¶
WithContext adds an fn context to a context context. It is unclear why this is an exported method but hey here ya go don't hurt yourself.
func WriteStatus ¶
WriteStatus will set the status code to return in the function response
Types ¶
type Context ¶
type Context interface {
// Config is a map of all env vars set on a function, the base set of fn
// headers in addition to any app and function configuration
Config() map[string]string
// Header are the headers sent to this function invocation
Header() http.Header
// ContentType is Header().Get("Content-Type") but with 15 less chars, you are welcome
ContentType() string
// CallID is the call id for this function invocation
CallID() string
// AppName is Config()["FN_APP_ID"]
AppID() string
// FnID is Config()["FN_FN_ID"]
FnID() string
// AppName is Config()["FN_APP_ID"]
AppName() string
// FnName is Config()["FN_FN_Name"]
FnName() string
// Tracing Context Data if available
TracingContextData() TracingContext
}
Context contains all configuration for a function invocation
func GetContext ¶
GetContext will return an fdk Context that can be used to read configuration and request information from an incoming request.
type HTTPContext ¶
type HTTPContext interface {
Context
// RequestURL is the request url from the gateway client http request
RequestURL() string
// RequestMethod is the request method from the gateway client http request
RequestMethod() string
}
HTTPContext contains all configuration for a function invocation sourced from an http gateway trigger, which will make the function appear to receive from the client request they were sourced from, with no additional headers.
type Handler ¶
type Handler interface {
// Serve contains a context with request configuration, the body of the
// request as a stream of bytes, and a writer to output to; user's may set
// headers via the resp writer using the fdk's SetHeader/AddHeader methods -
// if you've a better idea, pipe up.
Serve(ctx context.Context, body io.Reader, resp io.Writer)
}
Handler is a function handler, representing 1 invocation of a function
func HTTPHandler ¶
HTTPHandler makes a Handler from an http.Handler, if the function invocation is from an http trigger the request is identical to the client request to the http gateway (sans some hop headers).
type HandlerFunc ¶
HandlerFunc makes a Handler so that you don't have to!
type TracingContext ¶ added in v0.0.4
type TracingContext interface {
/**
* Returns true if tracing is enabled for this function invocation
* @return whether tracing is enabled
*/
IsTracingEnabled() bool
/**
* Returns the URL to be used in tracing libraries as the destination for
* the tracing data
* @return a string containing the trace collector URL
*/
TraceCollectorURL() string
/**
* Returns the current trace ID as extracted from Zipkin B3 headers if they
* are present on the request
* @return the trace ID as a string
*/
TraceId() string
/**
* Returns the current span ID as extracted from Zipkin B3 headers if they
* are present on the request
* @return the span ID as a string
*/
SpanId() string
/**
* Returns the parent span ID as extracted from Zipkin B3 headers if they
* are present on the request
* @return the parent span ID as a string
*/
ParentSpanId() string
/**
* Returns the value of the Sampled header of the Zipkin B3 headers if they
* are present on the request
* @return true if sampling is enabled for the request
*/
IsSampled() bool
/**
* Returns the value of the Flags header of the Zipkin B3 headers if they
* are present on the request
* @return the verbatim value of the X-B3-Flags header
*/
Flags() string
// ServiceName is Config()["FN_APP_ID"] + Config()["FN_FN_Name"]
ServiceName() string
}
TracingContext contains all configuration for a function invocated to get the tracing context data.
Source Files