bundle-linter

Static code analysis for Apigee proxy bundles to encourage API developers to use best practices and avoid anti-patterns.

This utility is intended to capture the best practices knowledge from across Apigee including our Global Support Center team, Customer Success, Engineering, and our product team in a tool that will help developers create more scalable, performant, and stable API bundles using the Apigee DSL.

Status

At this point we are focused on plugin execution and modelling the various lintable assets including Bundles, Proxies, Targets, Flows, Steps, and Policies.

Plugins that test these abstractions are being developed concurrently.

Reporters (the means to report out results), Ingesters (bundle loaders) are to be developed with Filesystem being the only supported means of loading a bundle and all reporting now going to console.

Usage

apigeelint -s sampleProxy/

Tests

The tests directory includes scripts to exercise a subset of rules. Overall linting can be tested with:

apigeelint -s ./test/sampleProxy/24Solver/apiproxy/

This sample includes many bad practices and as such generates a bit of noise.

Contributing

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Rules

The list of rules is a work in progress and expected to increase over time. As product features change, rules will change as well. Linting and reporting will fall into one of the following broad categories:

Linter	Status	Code	Name	Description
Bundle
	◻️	BN001	Bundle folder structure correctness.	Bundles have a clear structure.
	◻️	BN002	Extraneous files.	Ensure each folder contains approrpriate resources in the bundle.
	◻️	BN003	Cache Coherence	A bundle that includes cache reads should include cache writes with the same keys.
	◻️	BN004	Unused variables.	Within a bundle variables created should be used in conditions, resource callouts, or policies.
	✅	BN005	Unattached policies.	Unattached policies are dead code and should be removed from production bundles.
	✅	BN006	Bundle size - policies.	Large bundles are a symptom of poor design. A high number of policies is predictive of an oversized bundle.
	◻️	BN007	Bundle size - resource callouts.	Large bundles are a symptom of poor design. A high number of resource callouts is indicative of underutilizing out of the box Apigee policies.
	◻️	BN008	IgnoreUnresolvedVariables and FaultRules	Use of IgnoreUnresolvedVariables without the use of FaultRules may lead to unexepected errors.
	◻️	BN009	Statistics Collector - duplicate policies	Warn on duplicate policies when no conditions are present or conditions are duplicates.
Proxy Definition
	◻️	PD001	RouteRules to Targets	RouteRules should map to defined Targets.
	✅	PD002	Unreachable Route Rules - defaults	Only one RouteRule should be present without a condition
	✅	PD003	Unreachable Route Rules	RouteRule without a condition should be last.
	◻️	PD004	Condition Complexity	Overly complext Condition statements make RouteRules difficult to debug and maintain
Target Definition
	◻️	TD001	Mgmt Server as Target	Discourage calls to the Management Server from a Proxy.
	◻️	TD002	Use Target Servers	Encourage the use of target servers
Flow
	✅	FL001	Unconditional Flows	Only one unconditional flow will get executed. Error if more than one was detected.
Step
	✅	ST001	Empty Step	Empty steps clutter the bundle.
Policy
	◻️	PO001	JSON Threat Protection	A check for a body element must be performed before policy execution.
	◻️	PO002	XML Threat Protection	A check for a body element must be performed before policy execution.
	◻️	PO003	Extract Variables with JSONPayload	A check for a body element must be performed before policy execution.
	◻️	PO004	Extract Variables with XMLPayload	A check for a body element must be performed before policy execution.
	◻️	PO005	Extract Variables with FormParam	A check for a body element must be performed before policy execution.
	◻️	PO006	Policy Naming Conventions - default name	Policy names should not be default.
	◻️	PO007	Policy Naming Conventions - type indication	It is recommended that the policy name include an indicator of the policy type.
	◻️	PO008	Policy Name Attribute Conventions	It is recommended that the policy name attribute match the display name of the policy.
	◻️	PO009	Service Callout Target - Mgmt Server	Targetting management server may result in higher than expected latency use with caution.
	◻️	PO010	Service Callout Target - Target Server	Encourage use of target servers.
	◻️	PO011	Service Callout Target - Dynamic URLs	Error on dynamic URLs in target server URL tag.
	◻️	PO012	Service Callout Target - Script Target Node	JSHint, ESLint.
	✅	PO013	Resoure Call Out - Javascript	JSHint, ESLint.
	◻️	PO014	Resoure Call Out - Java	PMD, Checkstyle.
	◻️	PO016	Resoure Call Out - Python	Pylint.
	◻️	PO016	Statistics Collector - duplicate variables	Warn on duplicate variables.
	◻️	PO016	Statistics Collector - reserved variables	Warn on insertion of duplicate variables.
	◻️	PO017	Misconfigured - FaultRules/Fault Rule in Policy	FaultRules are configured in ProxyEndpoints and TargetEndpoints.
	◻️	PO018	Regex Lookahead/Lookbehind are Expensive - Threat Protection Policy	Regular expressions that include lookahead or lookbehind perform slowly on large payloads and are typically not required.
	✅	PO019	Reserved words as variables - ServiceCallout Request	Using "request" as the name of a Request may cause unexpected side effects.
	✅	PO020	Reserved words as variables - ServiceCallout Response	Using "response" as the name of a Response may cause unexpected side effects.
FaultRules
	◻️	FR001	No Condition on FaultRule	It's not a best practice to have a FaultRule without an outer condition, which automatically makes the FaultRule true.
Conditional
	◻️	CC001	Literals in Conditionals	Warn on literals in any conditional statement.
	◻️	CC002	Null Blank Checks	Blank checks should also check for null conditions. (to be reviewed)
	✅	CC003	Long condition statement	Conditions should not be long.
	◻️	CC004	Overly complex condition	Condition complexity should be limited to fix number of variables and conjunctions.
	◻️	CC005	Regex Lookahead/Lookbehind are Expensive - Conditions	Regular expressions that include lookahead or lookbehind perform slowly on large payloads and are typically not required.
	✅	CC006	Detect logical absurdities	Conditions should not have internal logic conflicts - warn when these are detected.

From an implementation perspective the focus is on plugin support and flexibility over performance. Compute is cheap.