|
| 1 | +// Copyright (c) HashiCorp, Inc. |
| 2 | +// SPDX-License-Identifier: MPL-2.0 |
| 3 | +package ephemeral |
| 4 | + |
| 5 | +import ( |
| 6 | + "context" |
| 7 | +) |
| 8 | + |
| 9 | +// EphemeralResource represents an instance of an ephemeral resource type. This is the core |
| 10 | +// interface that all ephemeral resources must implement. |
| 11 | +// |
| 12 | +// Ephemeral resources can optionally implement these additional concepts: |
| 13 | +// |
| 14 | +// - Configure: Include provider-level data or clients via EphemeralResourceWithConfigure |
| 15 | +// |
| 16 | +// - Validation: Schema-based or entire configuration via EphemeralResourceWithConfigValidators |
| 17 | +// or EphemeralResourceWithValidateConfig. |
| 18 | +// |
| 19 | +// - Renew: Handle renewal of an expired remote object via EphemeralResourceWithRenew. |
| 20 | +// Ephemeral resources can indicate to Terraform when a renewal must occur via the RenewAt |
| 21 | +// response field of the Open/Renew methods. Renew cannot return new result data for the |
| 22 | +// ephemeral resource instance, so this logic is only appropriate for remote objects like |
| 23 | +// HashiCorp Vault leases, which can be renewed without changing their data. |
| 24 | +// |
| 25 | +// - Close: Allows providers to clean up the ephemeral resource via EphemeralResourceWithClose. |
| 26 | +// |
| 27 | +// NOTE: Ephemeral resource support is experimental and exposed without compatibility promises until |
| 28 | +// these notices are removed. |
| 29 | +type EphemeralResource interface { |
| 30 | + // Metadata should return the full name of the ephemeral resource, such as |
| 31 | + // examplecloud_thing. |
| 32 | + Metadata(context.Context, MetadataRequest, *MetadataResponse) |
| 33 | + |
| 34 | + // Schema should return the schema for this ephemeral resource. |
| 35 | + Schema(context.Context, SchemaRequest, *SchemaResponse) |
| 36 | + |
| 37 | + // Open is called when the provider must generate a new ephemeral resource. Config values |
| 38 | + // should be read from the OpenRequest and new response values set on the OpenResponse. |
| 39 | + Open(context.Context, OpenRequest, *OpenResponse) |
| 40 | +} |
| 41 | + |
| 42 | +// EphemeralResourceWithRenew is an interface type that extends EphemeralResource to |
| 43 | +// include a method which the framework will call when Terraform detects that the |
| 44 | +// provider-defined returned RenewAt time for an ephemeral resource has passed. This RenewAt |
| 45 | +// response field can be set in the OpenResponse and RenewResponse. |
| 46 | +type EphemeralResourceWithRenew interface { |
| 47 | + EphemeralResource |
| 48 | + |
| 49 | + // Renew is called when the provider must renew the ephemeral resource based on |
| 50 | + // the provided RenewAt time. This RenewAt response field can be set in the OpenResponse and RenewResponse. |
| 51 | + // |
| 52 | + // Renew cannot return new result data for the ephemeral resource instance, so this logic is only appropriate |
| 53 | + // for remote objects like HashiCorp Vault leases, which can be renewed without changing their data. |
| 54 | + Renew(context.Context, RenewRequest, *RenewResponse) |
| 55 | +} |
| 56 | + |
| 57 | +// EphemeralResourceWithClose is an interface type that extends |
| 58 | +// EphemeralResource to include a method which the framework will call when |
| 59 | +// Terraform determines that the ephemeral resource can be safely cleaned up. |
| 60 | +type EphemeralResourceWithClose interface { |
| 61 | + EphemeralResource |
| 62 | + |
| 63 | + // Close is called when the provider can clean up the ephemeral resource. |
| 64 | + // Config values may be read from the CloseRequest. |
| 65 | + Close(context.Context, CloseRequest, *CloseResponse) |
| 66 | +} |
| 67 | + |
| 68 | +// EphemeralResourceWithConfigure is an interface type that extends EphemeralResource to |
| 69 | +// include a method which the framework will automatically call so provider |
| 70 | +// developers have the opportunity to setup any necessary provider-level data |
| 71 | +// or clients in the EphemeralResource type. |
| 72 | +type EphemeralResourceWithConfigure interface { |
| 73 | + EphemeralResource |
| 74 | + |
| 75 | + // Configure enables provider-level data or clients to be set in the |
| 76 | + // provider-defined EphemeralResource type. |
| 77 | + Configure(context.Context, ConfigureRequest, *ConfigureResponse) |
| 78 | +} |
| 79 | + |
| 80 | +// EphemeralResourceWithConfigValidators is an interface type that extends EphemeralResource to include declarative validations. |
| 81 | +// |
| 82 | +// Declaring validation using this methodology simplifies implementation of |
| 83 | +// reusable functionality. These also include descriptions, which can be used |
| 84 | +// for automating documentation. |
| 85 | +// |
| 86 | +// Validation will include ConfigValidators and ValidateConfig, if both are |
| 87 | +// implemented, in addition to any Attribute or Type validation. |
| 88 | +type EphemeralResourceWithConfigValidators interface { |
| 89 | + EphemeralResource |
| 90 | + |
| 91 | + // ConfigValidators returns a list of functions which will all be performed during validation. |
| 92 | + ConfigValidators(context.Context) []ConfigValidator |
| 93 | +} |
| 94 | + |
| 95 | +// EphemeralResourceWithValidateConfig is an interface type that extends EphemeralResource to include imperative validation. |
| 96 | +// |
| 97 | +// Declaring validation using this methodology simplifies one-off |
| 98 | +// functionality that typically applies to a single ephemeral resource. Any documentation |
| 99 | +// of this functionality must be manually added into schema descriptions. |
| 100 | +// |
| 101 | +// Validation will include ConfigValidators and ValidateConfig, if both are |
| 102 | +// implemented, in addition to any Attribute or Type validation. |
| 103 | +type EphemeralResourceWithValidateConfig interface { |
| 104 | + EphemeralResource |
| 105 | + |
| 106 | + // ValidateConfig performs the validation. |
| 107 | + ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse) |
| 108 | +} |
0 commit comments