---
title: Transaction
summary: Transaction represents a construct to coordinate concurrent actions for the same cache key.
url: https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/
---

**Kind:** Struct  
**Module:** [core](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/)  
**Package:** compute-sdk-go v1.11.0  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L522

```go
type Transaction struct {
	// contains filtered or unexported fields
}
```

Transaction represents a construct to coordinate concurrent actions
for the same cache key.

Transactions incorporate concepts of [request collapsing](https://developer.fastly.com/learning/concepts/request-collapsing/) and
[revalidation](https://developer.fastly.com/learning/concepts/stale/), though at a lower level that does not automatically
interpret HTTP semantics.

## Request collapsing

If there are multiple concurrent calls to [NewTransaction](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.NewTransaction/) for
the same object and that object is not present, only one of the
callers will be instructed to insert the item into the cache as part
of the transaction.  The other callers will block until the metadata
for the object has been inserted, and can then begin streaming its
contents out of the cache at the same time that the inserting caller
streams them into the cache.

## Revalidation

Similarly, if an item is usable but stale, and multiple callers
attempt a lookup concurrently, they will all be given access to the
stale item, but only one will be designated to perform an update (or
insertion) to freshen the item in the cache.

```go
useFoundItem := func(f *core.Found) {

}

buildContents := func() []byte {

	return []byte("hello world!")
}

shouldReplace := func(f *core.Found, contents []byte) bool {

	return true
}

tx, err := core.NewTransaction([]byte("my_key"), core.LookupOptions{})
if err != nil {
	panic(err)
}
defer tx.Close()

f, err := tx.Found()
switch err {
case nil:

	useFoundItem(f)

	if tx.MustInsertOrUpdate() {
		contents := buildContents()
		if shouldReplace(f, contents) {

			w, err := tx.Insert(core.WriteOptions{
				TTL:           time.Hour,
				SurrogateKeys: []string{"my_key"},
				Length:        uint64(len(contents)),
			})
			if err != nil {
				panic(err)
			}

			if _, err := w.Write(contents); err != nil {
				panic(err)
			}

			if err := w.Close(); err != nil {
				panic(err)
			}
		} else {

			if err := tx.Update(core.WriteOptions{
				TTL:           time.Hour,
				SurrogateKeys: []string{"my_key"},
			}); err != nil {
				panic(err)
			}
		}
	}

case core.ErrNotFound:

	if tx.MustInsert() {

		contents := buildContents()
		w, f, err := tx.InsertAndStreamBack(core.WriteOptions{
			TTL:           time.Hour,
			SurrogateKeys: []string{"my_key"},
			Length:        uint64(len(contents)),
		})
		if err != nil {
			panic(err)
		}

		if _, err := w.Write(contents); err != nil {
			panic(err)
		}

		if err := w.Close(); err != nil {
			panic(err)
		}

		useFoundItem(f)
	} else {
		panic(err)
	}

default:

	panic(err)
}
```

## Methods

### Cancel

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L731

```go
func (t *Transaction) Cancel() error
```

Cancel terminates the obligation to provide an object to the cache.

If there are concurrent transactional lookups that were blocked
waiting on this client to provide the item, one of them will be
chosen to be unblocked and given the [Transaction.MustInsertOrUpdate](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-MustInsertOrUpdate)
obligation.

Cancel does not close the transaction.  Callers must still call Close
to end the transaction and cleanup resources associated with it.

**Returns**

`error`

### Close

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L737

```go
func (t *Transaction) Close() error
```

Close ends the transaction and cleans up resources associated with
it.

**Returns**

`error`

### Found

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L569

```go
func (t *Transaction) Found() (*Found, error)
```

Found returns information about the found cached object, if one is
available.  If there is no cached object, [ErrNotFound] is returned.

Even if an object is found, the cache item might be stale and require
updating.  Use [Transaction.MustInsertOrUpdate](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-MustInsertOrUpdate) to determine whether
this transaction client is expected to update the cached object.

**Returns**

`(*Found, error)`

### Insert

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L634

```go
func (t *Transaction) Insert(opts WriteOptions) (WriteCloseAbandoner, error)
```

Insert creates a [WriteCloseAbandoner](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/interface.WriteCloseAbandoner/) used for inserting an object
into the cache for this transaction's key.  For the insertion to
complete successfully, the object must be fully written to the writer
and its Close method called.

If Close is not called, or the writer's Abandon method is called,
the insertion is incomplete and any concurrent lookups that may be
reading from the object as it is streamed into the cache may
encounter an error while reading.

Inserting an object into the cache will unblock other transactions
waiting on this object, streaming the contents to clients as the data
is written.

The provided write options must not include request headers, and this
will return [ErrInvalidArgument] if they do.

**Parameters**

- `opts`: `WriteOptions`

**Returns**

`(WriteCloseAbandoner, error)`

### InsertAndStreamBack

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L664

```go
func (t *Transaction) InsertAndStreamBack(opts WriteOptions) (WriteCloseAbandoner, *Found, error)
```

InsertAndStreamBack creates a [WriteCloseAbandoner](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/interface.WriteCloseAbandoner/) used for
inserting an object into the cache, as well as a new [Found](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Found/) that can
be used to stream the object back to the caller.

Inserting an object into the cache will unblock other transactions
waiting on this object, streaming the contents to clients as the data
is written.

The returned [Found](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Found/) allows the client inserting a cache object to
efficiently read back the contents of that item, avoiding the need to
buffer contents for copying to multiple destinations.  This pattern
is commonly required when caching an item that also must be provided
to, for example, the client response.

The provided write options must not include request headers, and this
will return [ErrInvalidArgument] if they do.

**Parameters**

- `opts`: `WriteOptions`

**Returns**

`(WriteCloseAbandoner, *Found, error)`

### MustInsert

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L595

```go
func (t *Transaction) MustInsert() bool
```

MustInsert returns true if a usable cached item was not found, and
this transaction client is expected to insert one.

This function will return false if any cached item was found, even if
stale.  Use [Transaction.MustInsertOrUpdate](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-MustInsertOrUpdate) instead to handle stale
items.

Use [Transaction.Insert](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Insert) to insert the object, or
[Transaction.Cancel](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Cancel) to exit the transaction without providing an
object.

**Returns**

`bool`

### MustInsertOrUpdate

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L614

```go
func (t *Transaction) MustInsertOrUpdate() bool
```

MustInsertOrUpdate returns true if a fresh cached item was not found,
and this transaction client is expected to insert a new item or
update a stale item.

A fresh cached item not being found could mean one of two things:
  - No cached item was found, or
  - A stale cached item was found.

Use [Transaction.MustInsert](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-MustInsert) or [Transaction.Found](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Found) to determine
whether a new cached item must be inserted.

Use:
  - [Transaction.Update](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Update) to freshen a found item by updating its metadata,
  - [Transaction.Insert](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Insert) to insert a new item including object data,
  - [Transaction.Cancel](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-Cancel) to exit the transaction without providing an object.

**Returns**

`bool`

### Update

**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L712

```go
func (t *Transaction) Update(opts WriteOptions) error
```

Update is used to update a stale object in the cache.

Updating an object freshens it by updating its metadata without
changing the object itself.

This method should only be called when
[Transaction.MustInsertOrUpdate](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/#method-MustInsertOrUpdate) is true and the item is found.
Otherwise, an [ErrInvalidOperation] will be returned.

NOTE: Updating a cached item will replace ALL of the configuration in
the underlying cache object.  If something is not set in the provided
[WriteOptions](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.WriteOptions/), it will revert to the default value.  This behavior
is likely to change in the future to use the existing configuration.
This change will be noted in a future changelog.

The provided write options must not include request headers, and this
will return [ErrInvalidArgument] if they do.

This method will return [ErrInvalidOperation] if the object is not
stale.

**Parameters**

- `opts`: `WriteOptions`

**Returns**

`error`