Functions

count_precompile_statements(
    log::LambdaFunctionInvocationLog,
  )::Int64

Counts the number of precompilation statements that were emitted during the Julia run-time. If the function has been precompiled or compiled with PackageCompiler, this should be zero.

create_lambda_function(
    remote_image::RemoteImage;
    role::Union{AWSRole, Nothing} = nothing,
    function_name::Union{Nothing, String} = nothing,
    timeout::Int64 = 60,
    memory_size::Int64 = 2000,
  )::LambdaFunction

Creates a function that exists on the AWS Lambda service. The function will use the given RemoteImage, and runs using the given AWS Role.

create_lambda_function(
    repo::ECRRepo;
    role::AWSRole = nothing,
    function_name::Union{Nothing, String} = nothing,
    image_tag::String = "latest",
    timeout::Int64 = 60,
    memory_size::Int64 = 2000,
  )::LambdaFunction

Creates a function that exists on the AWS Lambda service. The function will use the given ECR Repo, and runs using the given AWS Role. If given, the image_tag will decide which of the images in the ECR Repo is used.

create_local_image(
    responder::Responder;
    image_suffix::Union{Nothing, String} = nothing,
    aws_config::Union{Nothing, AWSConfig} = nothing,
    image_tag::String = "latest",
    no_cache::Bool = false,
    function_test_data::Union{Nothing, FunctionTestData} = nothing,
    build_at_path::Union{Nothing, AbstractString} = nothing,
    user_defined_labels::AbstractDict{String, String} = OrderedDict{String, String}(),
    dockerfile_update::Function = x -> x,
    build_args::AbstractDict{String, String} = OrderedDict{String, String}(),
    run_tests_during_package_compile::Bool = false,
  )::LocalImage

Creates a locally-stored docker image containing the specified responder. This can be tested locally, or directly uploaded to an AWS ECR Repo for use as an AWS Lambda function.

If function_test_data is passed, then this test data will be used to test the resulting docker image. It will also cause the responder function itself to be included in the package compiler process, improving the performance of the lambda function.

Use no_cache to construct the local image without using a cache; this is sometimes necessary if nothing locally has changed, but the image is querying a remote object (say, a github repo) which has changed.

If user_defined_labels are defined, these will be added to the generated LocalImage, as well as all subsequent types based on the LocalImage, like the remote image or the ultimate Lambda function. They can be retrieved using the get_labels function, alongside the Jot-generated labels.

dockerfile_update is a function that accepts the pre-generated Dockerfile as its only argument, and returns a new Dockerfile. The most likely use case for this is to add customized extensions to the generated Dockerfile. For example, passing (dockerfile) -> dockerfile * "RUN ssh-keygen -t rsa -f .ssh/id_rsa -N" will cause an SSH key to be created within the docker image.

build_args are arguments that are appended to the docker build command using the --build-arg command-line argument.

run_tests_during_package_compile tells Jot whether it should run the package's tests during the package compilation process. This will very likely cause additional code paths to be included in the package compilation process, and therefore can improve the performance of the resulting lambda function. However, it may add considerably to the image build time, particularly if your test suite is extensive.

delete!(con::Container)

Deletes the passed container from the local docker system. The Container instance continues to exist, but has its exists attribute set to false.

delete!(repo::ECRRepo)

Removes the passed ECRRepo instance from AWS ECR, and sets the exists attribute to false to indicate it no longer exists.

delete!(func::LambdaFunction)

Deletes a Lambda function hosted on AWS. The LambdaFunction instance continues to exist, but has its exists attribute set to false.

delete!(
  image::LocalImage;
  force::Bool=false,
)

Deletes a locally-stored docker image. The LocalImage instance continues to exist, but has its exists attribute set to false.

get_dockerfile(
    responder::Responder,
    user_defined_labels::AbstractDict{String, String} = AbstractDict{String, String}(),
    dockerfile_update::Function = x -> x,
  )::String

Returns contents for a Dockerfile. This function is called in create_local_image in order to create a local docker image.

get_ecr_repo(image::LocalImage)::Union{Nothing, ECRRepo}

Queries AWS and returns an ECRRepo instance that is associated with the passed local_image. Returns nothing if one cannot be found.

get_ecr_repo(repo_name::String)::Union{Nothing, ECRRepo}

Queries AWS and returns an ECRRepo instance with the passed repo_name. Returns nothing if one cannot be found.

create_lambda_components(
    res::Responder;
    image_suffix::Union{Nothing, String} = nothing,
    aws_config::Union{Nothing, AWSConfig} = nothing,
    image_tag::String = "latest",
    no_cache::Bool = false,
    julia_base_version::String = "1.8.4",
    julia_cpu_target::String = "x86-64",
    function_test_data::Union{Nothing, FunctionTestData} = nothing,
    user_defined_labels::AbstractDict{String, String} = OrderedDict{String, String}(),
  )::LambdaComponents

Creates a LocalImage from the given responder, creates a LambdaComponents object to store the local image, and then returns the LambdaComponents object.

Acts as an alternative to create_local_image, but returns a LambdaComponents rather than just the local image. This can be more convenient for keeping the components of a lambda function organized - for example: create_lambda_components(responder) |> with_remote_image! |> with_lambda_function! will run through the entire process of creating a local image, pushing that image to ECR, and then creating a Lambda function.

function get_all_aws_roles()::Vector{AWSRole}

Get all AWS roles from the current AWS Config.

get_all_containers(args::Vector{String} = Vector{String}())::Vector{Container}

Returns a list of containers currently available on the local machine.

args are additional arguments passed to the docker ps call that this function wraps.

get_all_ecr_repos(jot_generated_only::Bool = true)::Vector{ECRRepo}

Returns a vector of ECRRepos, representing all AWS-hosted ECR Repositories.

jot_generated_only specifies whether to filter for jot-generated repos only.

get_all_lambda_functions(jot_generated_only::Bool = true)::Vector{LambdaFunction}

Returns a vector of LambdaFunctions, representing all AWS-hosted Lambda functions.

jot_generated_only specifies whether to filter for jot-generated lambda functions only.

get_all_local_images(;
    args::Vector{String} = Vector{String}(),
    jot_generated_only::Bool = true,
  )::Vector{LocalImage}

Returns a vector of LocalImages, representing all locally-stored docker images.

args are passed to the call to docker image ls, that is used to populate this vector. jot_generated_only specifies whether to filter for jot-generated images only.

function get_all_remote_images(jot_generated_only::Bool = true)::Vector{RemoteImage}

Returns all remote images stored on AWS ECR. By default, filters for jot-generated images only.

get_invocation_time_breakdown(
    log::LambdaFunctionInvocationLog,
  )::InvocationTimeBreakdown

Returns an InvocationTimeBreakdown object, which stores how/where the total run-time was spent for a given invocation, in milliseconds.

get_lambda_function(function_name::String)::Union{Nothing, LambdaFunction}

Queries AWS and returns a LambdaFunction object, representing a Lambda Function hosted on AWS.

get_lambda_function(repo::ECRRepo)::Union{Nothing, LambdaFunction}

Queries AWS and returns a LambdaFunction object, representing a Lambda Function hosted on AWS. The Lambda function returned is based off the given ECRRepo instance.

get_local_image(
  identity::String,
)::Union{Nothing, LocalImage}

Returns a LocalImage object, representing a locally-stored docker image.

The passed identity string may be the repository name, or the docker image ID. If the image ID, it must be at least four characters in length.

get_remote_image(lambda_function::LambdaFunction)::RemoteImage

Queries AWS and returns a RemoteImage object, representing a docker image hosted on AWS ECR. The RemoteImage returned provides the code for the provided lambda_function.

get_remote_image(local_image::LocalImage)::Union{Nothing, RemoteImage}

Queries AWS and returns a RemoteImage instance corresponding to the given local_image.

If multiple valid images exist, this will return the first only. If none exists, returns nothing.

get_remote_image(identity::AbstractString)::Union{Nothing, RemoteImage}

Queries AWS and returns a RemoteImage instance corresponding to the given identity string.

The identity string will attempt to match on the name of the remote image, or the image's Digest.

If multiple valid images exist, this will return the first only. If none exists, returns nothing.

function get_responder(
    mod::Module,
    response_function::Symbol,
    response_function_param_type::Type{IT};
    registry_urls::Vector{<:AbstractString} = Vector{String}(),
  )::Responder{IT} where {IT}

Returns an Responder, a type that holds the function that will be used to respond to AWS Lambda calls.

mod is a module currently in scope, and response_function is a function within this module that you would like to use to respond to AWS Lambda calls.

response_function is a function within this module that you would like to use to respond to AWS Lambda calls. response_function_param_type specifies the type that the response function is expecting as its only argument.

registry_urls may be used to make additional julia registries available, the packages from which can then be used in the dependencies parameter.

function get_responder(
    path_url::String,
    response_function::Symbol,
    response_function_param_type::Type{IT};
    dependencies::Vector{<:AbstractString} = Vector{String}(),
    registry_urls::Vector{<:AbstractString} = Vector{String}(),
  )::Responder{IT} where {IT}

Returns an Responder, a type that holds the function that will be used to respond to AWS Lambda calls.

path_url may be either a local filesystem path, or a url.

If a filesystem path, it may point to either a script or a package. If a script, dependencies may be passed to specify any dependencies used in the script. If a package, the dependencies will be found automatically from its Project.toml.

If a url, it should be a remote package, for example the URL for a github repo. The url given will be passed to Pkg as a url, so any url valid in a PackageSpec will also be valid here, such as https://github.com/harris-chris/JotTest3

response_function is a function within this module that you would like to use to respond to AWS Lambda calls. response_function_param_type specifies the type that the response function is expecting as its only argument.

registry_urls may be used to make additional julia registries available, the packages from which can then be used in the dependencies parameter.

get_user_labels(l::Union{LocalImage, ECRRepo, RemoteImage, LambdaFunction})::Dict

Retrieves any user_defined labels for the given resource as a Dict of key=>value pairs.

invoke_function(
    request::Any,
    lambda_function::LambdaFunction;
    check_state::Bool=false,
  )::Any

Invokes a Lambda function, hosted on AWS. request is the argument that it will be called with. This will be automatically converted to JSON before sending, so should match the response_function_param_type of the responder used to create the function.

Returns the invoked Lambda function response, or throws an error if the invoked Lambda function has returned an error status.

If check_state is true, the function will wait for the AWS Lambda function to become available before sending the request. This can be useful if the Lambda function has been created within the last few seconds, since there is a short set-up time before it can be called.

invoke_function_with_log(
    request::Any,
    lambda_function::LambdaFunction;
    check_state::Bool=false,
  )::Tuple{Any, LambdaFunctionInvocationLog}

As per invoke_function, but returns a tuple of {Any, LambdaFunctionInvocationLog}, consisting of the result as well as log information about the invocation in the form of a LambdaFunctionInvocationLog.

is_container_running(con::Container)::Bool

Returns true if the given docker container is currently running (not stopped).

push_to_ecr!(image::LocalImage)::RemoteImage

Pushes the given local docker image to an AWS ECR Repo, a prerequisite of creating an AWS Lambda Function. If an ECR Repo for the given local image does not exist, it will be created automatically. Returns a RemoteImage object that represents the docker image that is hosted on the ECR Repo. The ECR Repo itself is an attribute of the RemoteImage.

run_image_locally(local_image::LocalImage; detached::Bool=true)::Container

Runs the given local image, starting a docker container. If detached, the container will run in the background. The container can be stopped/deleted by eg stop_container, delete!.

run_local_image_test(
    image::LocalImage,
    function_test_data::Union{Nothing, FunctionTestData} = nothing;
    then_stop::Bool = false,
  )::Tuple{Bool, Float64}

Runs a test of the given local docker image, defaulting to the standard jot test string if functiontestdata is not given. Returns a tuple of (test result, time) where time is the time taken for a response to be received, in seconds.

The test will use an already-running docker container, if one exists. If this is the case then the then_stop parameter tells the function whether to stop the docker container after running the test. If the run_test function finds no docker container already running, it will start one, and then shut it down afterwards. This is true regardless of the value of then_stop.

run_lambda_function_test(
    func::LambdaFunction,
    function_test_data::Union{Nothing, FunctionTestData};
    check_function_state::Bool = false,
  )::Tuple{Bool, Union{Missing, LambdaFunctionInvocationLog}}

Runs a test of the given Lambda Function, passing function_argument (if given), and expecting expected_response(if given). If a function_argument is not given, then it will merely test that any kind of response is received - this response may be an error JSON and the test will still pass, establishing only that the function can be contacted. Returns a tuple of {Any, LambdaFunctionInvocationLog}.

run_test(
    l::LambdaComponents,
    function_test_data::Union{Nothing, FunctionTestData} = nothing,
  )::Tuple{Bool, Union{Missing, LambdaFunctionInvocationLog, Float64}}

Tests the passed LambdaComponents instance.

The test runs on the most downstream object. So if the instance has a LambdaFunction, this will be tested. Otherwise, the attached LocalImage will be tested. If the LambdaComponents object has neither a local image or a lambda function, then it has nothing that can be tested and the function will throw an error.

Returns a tuple of {Test pass/fail, Test time taken in seconds}.

send_local_request(request::Any; local_port::Int64 = 9000)

Make a function call to a locally-running docker container and returns the value. A container can be initiated by eg run_image_locally.

show_lambdas()::Nothing

Displays a table of all objects generated using Jot.jl.

Each row of the table shows at least one of a Responder, a local docker image, a remote (hosted on AWS ECR) docker image, and an AWS-hosted Lambda function. The local docker image, remote docker image and lambda function on a given row of the table are guaranteed to share the same underlying function code.

The Responder column is colour-coded:

• Grey indicates that this path no longer exists.
• White indicates that this path still exists, but the code has changed since the objects shown

in the row were created.

• Blue indicates that the underlying code for this row (eg the code present in the local image,

remote image etc) is the same as is currently present at this path.

show_log_events(
    log::LambdaFunctionInvocationLog,
  )::Nothing

Presents a visual breakdown of the time spent for a given Lambda function invocation. All logged events will be shown here.

show_observations(
    log::LambdaFunctionInvocationLog,
  )::Nothing

Presents a visual breakdown of the time spent for a given Lambda invocation. Only Jot observation points will be shown here. See the 'Debugging Performance' page for more details of this.

stop_container(con::Container)

Stops the given docker container, if currently running.

with_remote_image!(l::LambdaComponents)::LambdaComponents

Adds a 'RemoteImageobject to the passedLambdaComponents` instance. Will error if the instance has neither an existing remote image or local image.

with_lambda_function!(l::LambdaComponents)::LambdaComponents

Adds a 'LambdaFunctioninstance to the passedLambdaComponents` instance. Will error if the instance has neither an existing remote image, local image or lambda function.